MongoDB MCP Server Configuration Guide

mongosh "mongodb:///analytics" --eval "db.runCommand({ ping: 1 })"

// Switch to target application database
use analytics;

// Create dedicated unprivileged analyst user
db.createUser({
  user: "mcp_analyst_ro",
  pwd: "Secure_NoSQL_Password_2026!",
  roles: [
    { role: "read", db: "analytics" }
  ]
});

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": ["/opt/mcp-servers/mongodb/dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb://mcp_analyst_ro:Secure_NoSQL_Password_2026!@/analytics?authSource=analytics",
        "DATABASE_NAME": "analytics"
      }
    }
  }
}

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb://mcp_analyst_ro:Secure_NoSQL_Password_2026!@/analytics?authSource=analytics",
        "DATABASE_NAME": "analytics"
      }
    }
  }
}

[mcp_servers.mongodb]
command = "node"
args = ["/opt/mcp-servers/mongodb/dist/index.js"]

[mcp_servers.mongodb.env]
MONGODB_URI = "mongodb://mcp_analyst_ro:Secure_NoSQL_Password_2026!@/analytics?authSource=analytics"
DATABASE_NAME = "analytics"

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { MongoClient, Document } from 'mongodb';

const uri = process.env.MONGODB_URI || 'mongodb:///analytics';
const dbName = process.env.DATABASE_NAME || 'analytics';

const client = new MongoClient(uri, {
  maxPoolSize: 10,
  serverSelectionTimeoutMS: 5000
});

const server = new Server(
  { name: 'mongodb-mcp-server', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'list_collections',
        description: 'List all collections in the configured database.',
        inputSchema: { type: 'object', properties: {} }
      },
      {
        name: 'find_documents',
        description: 'Query documents in a collection using BSON filter expressions. Maximum 50 documents returned.',
        inputSchema: {
          type: 'object',
          properties: {
            collection: { type: 'string', description: 'Collection name' },
            filter: { type: 'object', description: 'MongoDB query filter expression (e.g. {"status": "active"})' },
            projection: { type: 'object', description: 'Field projection map (e.g. {"email": 1, "created_at": 1})' },
            limit: { type: 'number', default: 20, maximum: 50, description: 'Number of documents to return' }
          },
          required: ['collection']
        }
      },
      {
        name: 'run_aggregation',
        description: 'Execute a multi-stage aggregation pipeline across a collection.',
        inputSchema: {
          type: 'object',
          properties: {
            collection: { type: 'string', description: 'Collection name' },
            pipeline: { type: 'array', items: { type: 'object' }, description: 'Array of aggregation stages ($match, $group, $sort)' }
          },
          required: ['collection', 'pipeline']
        }
      }
    ]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  const db = client.db(dbName);

  try {
    if (name === 'list_collections') {
      const collections = await db.listCollections().toArray();
      const names = collections.map(c => c.name);
      return {
        content: [{ type: 'text', text: JSON.stringify(names, null, 2) }]
      };
    }

    if (name === 'find_documents') {
      const collName = args?.collection as string;
      const filter = (args?.filter as Document) || {};
      const projection = (args?.projection as Document) || {};
      const limit = Math.min(Number(args?.limit) || 20, 50);

      const docs = await db.collection(collName)
        .find(filter, { projection })
        .limit(limit)
        .toArray();

      return {
        content: [{ type: 'text', text: JSON.stringify(docs, null, 2) }]
      };
    }

    if (name === 'run_aggregation') {
      const collName = args?.collection as string;
      const pipeline = (args?.pipeline as Document[]) || [];

      // Append safety limit stage to prevent runaway pipeline outputs
      pipeline.push({ $limit: 50 });

      const results = await db.collection(collName).aggregate(pipeline).toArray();

      return {
        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }]
      };
    }

    throw new Error(`Tool '${name}' is not recognized.`);
  } catch (err: any) {
    return {
      isError: true,
      content: [{ type: 'text', text: `MongoDB Error: ${err.message}` }]
    };
  }
});

async function main() {
  await client.connect();
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  process.stderr.write(`Fatal MongoDB server error: ${err.message}\n`);
  process.exit(1);
});

{
  "jsonrpc": "2.0",
  "id": "mongo-find-01",
  "method": "tools/call",
  "params": {
    "name": "find_documents",
    "arguments": {
      "collection": "events",
      "filter": { "type": "signup" },
      "limit": 2
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "mongo-find-01",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  {\"_id\": \"660ab18f921a4f00\", \"type\": \"signup\", \"user_id\": \"usr_401\"},\n  {\"_id\": \"660ab18f921a4f01\", \"type\": \"signup\", \"user_id\": \"usr_402\"}\n]"
      }
    ]
  }
}