mongodb

This MongoDB MCP Server exposes read-only access to your MongoDB databases through the MCP (Model Context Protocol) interface. It supports essential data exploration and analysis tasks such as listing databases and collections, inferring collection schemas, executing read-only queries with filtering, projection, sorting, and limiting, and performing safe aggregations. Additional capabilities include text search on indexed fields, geospatial queries, counting and sampling documents, retrieving statistics and index information, and exporting results as JSON or CSV. The server also provides helpful guidance for visualization and intelligent safety checks to prevent unintended data modifications.

To use the server, connect an MCP-enabled client (such as Claude Desktop/Web or Claude Code) to the mongodb MCP server endpoint. Provide the required MONGODB_URI for authentication, and optionally set MONGODB_DEFAULT_DATABASE for default query context. Once connected, you can issue standard MCP tool commands (e.g., list databases, run queries, fetch document samples) and receive structured results suitable for downstream AI-assisted analysis and visualization.

Prerequisites:

• Node.js and npm installed on your system
• Access to a MongoDB instance (with read permissions)
• A path or deployment method to host the MCP server code

1. Install dependencies

npm install

2. Build the server (if your project requires a build step)

npm run build

3. (Optional) Run in watch mode for development

npm run watch

4. Prepare environment variables

• MONGODB_URI: Your MongoDB connection string (including credentials if required)
• MONGODB_DEFAULT_DATABASE: (Optional) Default database name for queries

5. Run the MCP server

# Example runner command
node /path/to/jonfreeland-mongodb-mcp/build/index.js

6. Verify the server is reachable via your MCP client (Claude Desktop/Web/Code) by configuring the server as described in the README

Tips and common issues:

• Ensure MONGODB_URI is kept secure; avoid exposing it in client configurations or logs.
• The server is read-only by design; attempting write-style operations will be rejected or ignored.
• If you encounter connection errors, verify network access to the MongoDB instance and that the credentials have the appropriate read permissions.
• For Claude Code integration, ensure the command and path point to the compiled MCP server index.js file and include the necessary -e environment variables when using the add command.
• When using text search or geospatial queries, make sure relevant indexes (text, 2dsphere) exist on the target collections to achieve expected performance.
• Use the MCP Inspector during debugging to inspect the protocol messages and responses.
• If you need to override defaults, you can set MONGODB_DEFAULT_DATABASE to a sensible fallback database.