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

Non-Read-Only Mode Tools

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:

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