MongoDB

You can query and analyze your MongoDB data safely through a read-only MCP server that exposes MongoDB capabilities via standardized tools. This setup lets you explore databases, infer schemas, run read-only queries and aggregations, and export results without risking data modification.

How to use

Connect your MCP client to the MongoDB MCP Server and use its read-only tools to explore databases, inspect schemas, run queries, and export results. You can perform actions such as listing databases and collections, describing collection schemas from sample documents, filtering and projecting results, running safe aggregation pipelines, and exporting results as JSON or CSV. You will also get insights like index information, statistics, and query plans to help you understand performance without changing data.

How to install

Prerequisites you need before installing: Node.js and npm, and access to a MongoDB instance with read permissions.

# 1) Install dependencies
npm install

# 2) Build the server
npm run build

# 3) (Optional) Run in watch mode for auto-rebuild during development
npm run watch

Additional setup and usage notes

Configure the server with your MongoDB connection string. You should provide the MongoDB URI via the environment variable MONGODB_URI and, if desired, set a default database with MONGODB_DEFAULT_DATABASE. The server is read-only by design, so you do not need to configure write permissions.

Example environment setup for development or testing: set MONGODB_URI to your MongoDB connection string, and optionally set MONGODB_DEFAULT_DATABASE to your preferred default. Then start or run the server as described in the build/run steps.

Security and troubleshooting

Security: Use a MongoDB user with read-only permissions and store connection strings securely in environment variables. The server enforces read-only behavior for all aggregation steps to prevent data modification.

If you encounter issues, build and run logs can help you diagnose startup problems, missing environment variables, or connection issues to MongoDB. Ensure MONGODB_URI is correctly set and reachable from your host.

Notes on configuration and usage patterns

This MCP server offers a range of capabilities such as database exploration, schema inference, querying with filters and projections, safe aggregations, text search, geospatial queries, and data export. Use the tools to gain data insights and prepare results for visualization without altering the underlying data.

Troubleshooting and debugging

If debugging is needed, review startup logs for environment variable issues or connection failures. Since MCP servers communicate over stdio, you can use debugging tools that attach to the running process or inspect logs produced by the server during startup.

Available tools

listDatabases

List available databases in the connected MongoDB instance.

listCollections

List collections within a specified database.

inferSchema

Infer collection schema from sample documents to understand data types and structure.

query

Execute read-only MongoDB queries with filtering, projection, sorting, and limiting.

aggregateReadOnly

Run read-only aggregation pipelines with safety validation to prevent writes.

textSearch

Perform full-text search on collections with text indexes.

geoQuery

Run geospatial queries such as near, within, and intersects on location data.

countDocuments

Count documents matching a query.

sampleDocuments

Retrieve a random sample of documents.

findByIds

Find documents by a list of IDs.

getStatistics

Return collection statistics and index information.

explainQuery

Get query execution plans to analyze performance.

distinctValues

Get distinct values for a field.

fieldDistributions

Provide data distributions for fields across a collection.

exportJSON

Export query results as JSON.

exportCSV

Export query results as CSV.

visualizationHints

Receive intelligent suggestions for data visualization based on results.