mcp-mongo

This MCP server enables large language models to interact with a MongoDB database through a standardized set of capabilities. It can inspect collection schemas via automatic inference from sample documents, perform standard MongoDB operations like find, insert, update, and create indexes, and run aggregation pipelines with optional explain plans. It also supports a read-only mode to protect data by routing operations through a secondary read preference. Use this server when you want to expose MongoDB data and common operations to an LLM-driven workflow in a safe, structured way.

To start using it, run the server with your MongoDB connection URI. The server exposes tools for querying collections, performing updates or inserts (when not in read-only mode), and inspecting collection schemas. When combined with compatible MCP clients, you can craft prompts that leverage these tools to retrieve data, modify documents, or analyze collections without exposing raw MongoDB commands directly to the model.

Prerequisites:

• Node.js v14+ and npm installed on your machine
• Access to a MongoDB instance (local or remote)

Installation steps:

1. Verify Node.js and npm versions

node -v
npm -v

2. Install or run the MCP server via npx (no global install required)

npx -y mcp-mongo-server mongodb://localhost:27017/database

3. If you plan to pin a specific version, you can install the package temporarily and run it from there:

npx -y @mcp/mcp-mongo-server@latest mongodb://localhost:27017/database

4. Alternative: use an environment-aware script or package.json script to start with a specific URI, e.g.

"scripts": {
  "start-mongo-mcp": "npx -y mcp-mongo-server mongodb://YOUR_URI_HERE"
}

5. Configure environment variables as needed (see Environment Variables below).

Environment variables can customize behavior:

• MCP_MONGODB_URI: MongoDB connection URI to use by default
• MCP_MONGODB_READONLY: Enable read-only mode by default (set to 'true' to enable) Common issues:
• Ensure the MongoDB URI is reachable from the host running the MCP server
• If read-only mode is enabled, write operations will be blocked while read queries and aggregations remain available
• When using authentication, ensure credentials are included securely in the URI and not exposed in logs
• Check your MongoDB user permissions to avoid authorization errors during inserts/updates If you encounter issues, consult the docs in docs/integration.md and docs/tools.md, and verify your environment variables map to the intended behavior.