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).