mongodb-mcp

MongoDB MCP Server

Also available in Russian: README-ru.md

  

Note: This project is designed for my personal needs. I do not plan to expand its functionality with features I don't use or cannot verify. You are free to submit suggestions and pull requests, but I make no guarantee that everything will be accepted.

MCP server for comprehensive MongoDB integration with the following capabilities:

• Database operations - connect to MongoDB instances, list databases and collections
• Document management - find, aggregate, and count documents
• Schema analysis - analyze collection schemas and indexes
• Query tools - execute queries and aggregations with full MongoDB syntax
• Connection management - manage MongoDB connections with read-only mode support
• Streaming file export - streaming save to files for large datasets
• Read-only mode - safe read-only operations to prevent accidental data modifications
• Monitoring - database statistics, performance metrics, and MongoDB logs
• Query Analysis - execution plan analysis for performance optimization

Table of Contents

• Table of Contents
• Requirements
• Configuration for Qwen Code
• Configuration for VS Code Cline
• MCP Tools
• Read-Only Mode Tools
• Non-Read-Only Mode Tools
• Security considerations
• Concurrency considerations
• Local Development

Requirements

• Node.js ≥ 22 (Node 20 reached EOL on 2026-04-30)
• Environment variables:
• MONGODB_MCP_CONNECTION_STRING — MongoDB connection string (mongodb:// or mongodb+srv:// format)
• MONGODB_MCP_DEFAULT_DATABASE — optional default database name for operations
• MONGODB_MCP_TIMEZONE — optional timezone for date operations (default: Europe/Moscow), must be a valid IANA timezone identifier (e.g., Europe/London, America/New_York, Asia/Tokyo)

Configuration for Qwen Code

To use this MCP server with Qwen Code, add to ~/.qwen/settings.json:

{
  "mcpServers": {
    "mongodb-mcp": {
      "command": "npx",
      "args": ["-y", "@vitalyostanin/mongodb-mcp@latest"],
      "env": {
        "MONGODB_MCP_CONNECTION_STRING": "mongodb://localhost:27017"
      }
    }
  }
}

Note: This configuration uses npx to run the published package. For local development, use "command": "node" with "args": ["/absolute/path/to/mongodb-mcp/dist/index.js"]. The MONGODB_MCP_TIMEZONE environment variable is optional.

Configuration for VS Code Cline

To use this MCP server with Cline extension in VS Code:

1. Open VS Code with Cline extension installed
2. Click the MCP Servers icon in Cline's top navigation
3. Select the "Configure" tab and click "Configure MCP Servers"
4. Add the following configuration to cline_mcp_settings.json:

{
  "mcpServers": {
    "mongodb-mcp": {
      "command": "npx",
      "args": ["-y", "@vitalyostanin/mongodb-mcp@latest"],
      "env": {
        "MONGODB_MCP_CONNECTION_STRING": "mongodb://localhost:27017"
      }
    }
  }
}

Note: This configuration uses npx to run the published package. For local development, use "command": "node" with "args": ["/absolute/path/to/mongodb-mcp/dist/index.js"]. The MONGODB_MCP_TIMEZONE environment variable is optional.

MCP Tools

Read-Only Mode Tools

| Tool | Description | Main Parameters | | --- | --- | --- | | service-info | Get MongoDB service information, environment configuration, version, and current timezone | — | | connect | Establish connection to MongoDB using connection string | — | | disconnect | Disconnect from MongoDB | — | | list_databases | List all databases in the MongoDB instance | — | | db_stats | Get statistics for a specific database | database — database name | | list_collections | List all collections for a given database | database — database name | | collection_schema | Analyze the schema for a collection | database — database name, collection — collection name, optionally sampleSize (default 50) | | collection_indexes | Describe the indexes for a collection | database — database name, collection — collection name | | collection_storage_size | Get the size of a collection | database — database name, collection — collection name | | find | Run find queries against a MongoDB collection | database — database name, collection — collection name, optionally filter, limit (default 10), projection, sort | | count | Count documents in a MongoDB collection | database — database name, collection — collection name, optionally query — filter for counting | | explain | Returns statistics describing the execution of the winning plan chosen by the query optimizer | database — database name, collection — collection name, method — method object with name and arguments, optionally verbosity (default 'queryPlanner') | | mongodb_logs | Returns the most recent logged mongod events | optionally limit (default 50), type (default 'global', or 'startupWarnings') |

Non-Read-Only Mode Tools

| Tool | Description | Main Parameters | | --- | --- | --- | | aggregate | Run an aggregation against a MongoDB collection | database — database name, collection — collection name, pipeline — array of aggregation stages, noLimit — disable the automatic $limit stage (useful for pipelines ending with $out or $merge) | | insert | Insert one or multiple documents into a MongoDB collection | database — database name, collection — collection name, document — single document to insert, documents — array of documents to insert (use instead of single document) | | update | Update one or multiple documents in a MongoDB collection | database — database name, collection — collection name, filter — filter to match documents for update, update — update operations to perform, upsert — if true, creates a new document if no documents match the filter (default: false), multi — if true, updates all matching documents (updateMany), otherwise updates only one (updateOne) (default: false) | | delete | Delete one or multiple documents from a MongoDB collection | database — database name, collection — collection name, filter — filter to match documents for deletion, multi — if true, deletes all matching documents (deleteMany), otherwise deletes only one (deleteOne) (default: false) | | create-index | Create an index on a MongoDB collection | database — database name, collection — collection name, keys — index specification document (e.g., { field: 1 } for ascending, { field: -1 } for descending), options — additional index options (e.g., { unique: true, sparse: true }) | | drop-index | Drop an index from a MongoDB collection | database — database name, collection — collection name, index — index name or index specification document to drop | | create-collection | Create a new collection in a MongoDB database | database — database name, collection — collection name to create, options — additional collection options (e.g., { capped: true, size: 1024 }) | | drop-collection | Drop a collection from a MongoDB database | database — database name, collection — collection name to drop |

Note: The server runs in read-only mode by default to prevent accidental data modifications. In read-only mode, all write operations are blocked including:

• Database-level operations: insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, createIndex, dropIndex, dropDatabase, renameCollection, etc.
• Collection-level operations: insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, findOneAndReplace, findOneAndUpdate, findOneAndDelete, bulkWrite, createIndex, dropIndex, drop, etc.
• Aggregation stages that modify data: $out, $merge

The following aggregation stages are restricted in read-only mode: $out, $merge. These stages are only available when the server is running in read-write mode.

Security considerations

Recommendations for safe production use of the MCP server:

• Use TLS for remote MongoDB clusters. Prefer mongodb+srv:// (TLS is implied) or set tls=true explicitly in a regular mongodb:// connection string. Plaintext connections expose credentials and query payloads to anyone on the network path.
• Apply least-privilege roles. Create a dedicated MongoDB user with read-only access to only the databases you need. Avoid root, dbAdmin, or any role that grants eval / scripting privileges. Default to read-only mode unless write tools are required.
• Keep the connection string out of MCP host args. Configure MONGODB_MCP_CONNECTION_STRING via environment variables (e.g., .env file) rather than passing it through args of the MCP host configuration — args are typically logged when the host launches the server, leaking the password.
• Disable server-side JavaScript. The MCP server already blocks $where, $function, and $accumulator operators in queries. For defence in depth, run the MongoDB server itself with --javascriptEnabled=false (or the equivalent security.javascriptEnabled: false in mongod.conf).
• Restrict the export directory. When using file-export tools, set MONGODB_MCP_EXPORT_DIR to a directory accessible only to the MCP user (chmod 700). Other users on the machine should not be able to read the dumps that write tools produce.

Concurrency considerations

The MCP server does not provide transactional or ordering guarantees beyond what MongoDB itself enforces. Plan multi-step interactions accordingly:

• Tools are independent operations. Each call runs in its own implicit context; the server does not start multi-statement transactions or share a ClientSession across calls. Design atomic multi-step flows by encoding preconditions into the filter of the same update / delete call, rather than chaining a separate find followed by a mutating call.
• Singleton client, parallel operations. A single MongoClient is shared across all tool calls. Only connect / disconnect are serialised through an internal mutex; ordinary operations (find, aggregate, insert, etc.) execute concurrently against the cluster, with no cross-tool ordering imposed by the MCP server.
• Connection state is a snapshot. getConnectionInfo() returns the state at the moment of the call. For decisions that depend on connectivity, rely on the result of the next operation rather than a preceding isConnected check — the connection may drop between the two.
• File-export uses wx. Tools that write files open the target with the wx flag and will not overwrite an existing file. Concurrent calls targeting the same filePath will fail with EEXIST; callers must pick a fresh path (e.g., include a timestamp or per-call suffix).

Local Development

Quick reference for working with the source.

Prerequisites:

• Node.js as specified in .nvmrc (current LTS, ≥ 22). With nvm: nvm use.
• npm.

Setup:

git clone https://github.com/VitalyOstanin/mongodb-mcp.git
cd mongodb-mcp
npm install

Common scripts:

| Script | Purpose | | ----------------------- | ---------------------------------------------------------------- | | npm run build | Compile TypeScript to dist/ (tsconfig.build.json) and chmod the CLI entrypoint | | npm run dev | Run index.ts directly via tsx watch for iterative work | | npm start | Run the compiled server from dist/ | | npm run typecheck | Type-check sources + tests (tsconfig.json, no emit) | | npm run typecheck:tests | Type-check with extra strict flags (tsconfig.test.json) | | npm run lint | Run ESLint | | npm run lint:fix | Run ESLint with --fix | | npm test | Run the Vitest test suite once | | npm run test:watch | Run Vitest in watch mode | | npm run test:coverage | Run Vitest with v8 coverage (opt-in; threshold gate enforced) | | npm run test:debug | Run Vitest sequentially (--no-file-parallelism) |

Local connection example:

export MONGODB_MCP_CONNECTION_STRING="mongodb://localhost:27017"
npm run dev

Layout:

• index.ts — CLI entry point.
• src/server.ts — MCP server bootstrap.
• src/mongodb-client.ts — singleton MongoDB client with read-only Proxy.
• src/tools/ — one MCP tool per file plus its *.test.ts.
• src/utils/ — shared helpers (streaming exports, schema fragments, date handling, redaction).