MongoDB MCP Server

Stdio Model Context Protocol server that lets an IDE agent read and write MongoDB through typed, allowlisted tools.

This transport is stdio-only. Do not expose it on a public network without additional auth and a hardened deployment model. The process trusts the local MCP host (OS user / IDE); there is no separate login layer.

Features

Also registers a resource template: mongodb://collection/{name}.

Safety defaults

• Fail closed on collections: require MCP_ALLOWED_COLLECTIONS or explicit MCP_ALLOW_ALL_COLLECTIONS=true

• Collection names must match ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$

• Rejects $where / $function / $accumulator / $jsonSchema / $expr

• Caps $regex length and object nesting depth

• Blocks dangerous aggregation stages ($out / $merge / $function / admin stages); $lookup / $unionWith targets must pass the allowlist

• Caps limit at MCP_MAX_LIMIT (default 100)

• Soft-deleted documents (deletedAt) are hidden from reads unless requested

• Hard delete disabled unless MCP_ALLOW_HARD_DELETE=true

• Optional MCP_READ_ONLY=true disables all mutating tools

• Structured audit events + sanitized tool errors on stderr (stdout stays clean for MCP framing)

Related MCP server: Mongo-MCP

Quick start

# Start MongoDB
docker compose up -d mongo

# Install and run (dev)
cp .env.example .env
npm install
npm run dev

Production build:

npm run build
npm start

Cursor MCP config

Add to your MCP settings (path varies by Cursor version):

{
  "mcpServers": {
    "mongo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27018/mcp-server",
        "MCP_ALLOWED_COLLECTIONS": "notes,tasks"
      }
    }
  }
}

For local iteration without building:

{
  "mcpServers": {
    "mongo": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-server/src/index.ts"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27018/mcp-server",
        "MCP_ALLOWED_COLLECTIONS": "notes,tasks"
      }
    }
  }
}

Environment

Scripts

docker compose up -d mongo
npm run test:integration

Docker

Mongo only (typical for local MCP + host Node process):

docker compose up -d mongo

Optional image build (stdio still expected from the client):

docker compose --profile app build

Project layout

src/
  index.ts              # stdio bootstrap + secure config check
  loadEnv.ts            # optional .env loader
  server.ts             # McpServer wiring
  config.ts             # env config
  database/mongo.ts     # connection + dynamic models
  security/             # validation, access gates, audit log
  tools/                # tool handlers + Zod schemas
  resources/            # collection resources