MongoDB MCP Server

A read-only Model Context Protocol (MCP) server for querying MongoDB databases. Designed to be used with MCP-compatible clients like Claude Code, Claude Desktop, etc.

Quick Start

Run directly with npx — no installation needed:

MONGODB_URI="mongodb://localhost:27017" npx mongodb-mcp

Or install globally:

npm install -g mongodb-mcp

Environment Variables

| Variable | Required | Description | | ------------- | -------- | ------------------------------------------------ | | MONGODB_URI | Yes | MongoDB connection string (e.g. mongodb://localhost:27017 or mongodb+srv://...) |

Configuration

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["mongodb-mcp"],
      "env": {
        "MONGODB_URI": "mongodb+srv://user:[email protected]/dbname"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["mongodb-mcp"],
      "env": {
        "MONGODB_URI": "mongodb+srv://user:[email protected]/dbname"
      }
    }
  }
}

Tools

list_databases

Lists all databases on the connected MongoDB instance.

list_collections

Lists all collections in a given database.

| Parameter | Type | Description | | ---------- | ------ | ----------------- | | database | string | The database name |

list_indexes

Lists all indexes on a collection.

| Parameter | Type | Description | | ------------ | ------ | ------------------- | | database | string | The database name | | collection | string | The collection name |

run_aggregation

Runs an aggregation pipeline on a collection.

| Parameter | Type | Description | | ------------ | -------- | ---------------------------- | | database | string | The database name | | collection | string | The collection name | | pipeline | object[] | The aggregation pipeline stages |

run_aggregation_to_file

Runs an aggregation pipeline and writes results to a JSON file on disk instead of returning them over MCP. Returns only metadata (document count, file path, file size), which avoids loading large result sets into the agent's context window. Use CLI tools like jq, head, or the Read tool to selectively inspect the output file.

| Parameter | Type | Description | | ------------- | -------- | ------------------------------------------------ | | database | string | The database name | | collection | string | The collection name | | pipeline | object[] | The aggregation pipeline stages | | output_path | string | Absolute file path where JSON results are written |

Safety

• Read-only mode — Write stages ($out, $merge) in aggregation pipelines are rejected with an error.
• Query timeout — Aggregation queries have a 50-second server-side timeout (maxTimeMS) to prevent runaway queries.
• Read preference — The connection uses secondaryPreferred read preference as defense in depth.

Development

npm run dev    # watch mode
npm run build  # compile TypeScript
npm start      # run the compiled server

License

MIT