{"id":11357,"library":"mongodb-mcp-server","title":"MongoDB MCP Server","description":"The MongoDB MCP Server is the official implementation of the Model Context Protocol (MCP) designed to enable AI agents and large language models (LLMs) to interact with MongoDB databases using natural language. It connects various MongoDB deployments (Atlas, Community Edition, Enterprise Advanced) to MCP-supported AI clients such as Cursor, GitHub Copilot, and Claude Desktop. The server provides a rich set of tools for data exploration, database operations (including querying, indexing, and CRUD operations), Atlas management tasks, and performance optimization via integrated Performance Advisor tools. The current stable version is 1.9.0, with a cadence of frequent pre-releases and regular minor version updates. Key differentiators include its seamless integration with MongoDB Atlas, support for local Atlas deployments (requiring Docker), a simplified setup utility (`npx mongodb-mcp-server setup`), and advanced features like automatic vector embedding generation when configured with a Voyage AI API key.","status":"active","version":"1.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/mongodb-js/mongodb-mcp-server","tags":["javascript","typescript"],"install":[{"cmd":"npm install mongodb-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add mongodb-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add mongodb-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary function for programmatically starting the MCP server. Most common usage is via `npx` or AI client configuration, but programmatic control is available.","symbol":"startServer","correct":"import { startServer } from 'mongodb-mcp-server';"},{"note":"Represents the server's configuration interface, useful for type-checking when creating custom configurations. Imported as a type.","wrong":"import { Config } from 'mongodb-mcp-server';","symbol":"Config","correct":"import { type Config } from 'mongodb-mcp-server';"},{"note":"The underlying class for the Model Context Protocol server. While `startServer` is typically used for quick setup, this class can be instantiated for more advanced programmatic control over the server lifecycle and custom tool integration.","symbol":"Server","correct":"import { Server } from 'mongodb-mcp-server';"}],"quickstart":{"code":"import { startServer } from 'mongodb-mcp-server';\n\n// To run the server programmatically, you must provide a MongoDB connection string.\n// This can be via environment variables (MONGODB_URI, ATLAS_CLIENT_ID, ATLAS_PRIVATE_KEY)\n// or passed directly in the configuration object.\n\n// Ensure you have a MongoDB connection string set as an environment variable\n// or replace process.env.MONGODB_URI with your actual connection string.\n// For Atlas API credentials, set ATLAS_CLIENT_ID and ATLAS_PRIVATE_KEY.\n\nconst connectionString = process.env.MONGODB_URI ?? 'mongodb://localhost:27017/mcp-db';\n\nconst serverConfig = {\n  connectionString: connectionString,\n  port: 3000,\n  readOnly: false, // Set to true to disable write operations\n  logLevel: 'info' // 'debug', 'info', 'warn', 'error'\n};\n\nasync function main() {\n  try {\n    console.log('Starting MongoDB MCP Server...');\n    const server = await startServer(serverConfig);\n    console.log(`MongoDB MCP Server listening on port ${serverConfig.port}`);\n\n    // Example: Graceful shutdown\n    process.on('SIGINT', async () => {\n      console.log('SIGINT received, shutting down server...');\n      await server.stop();\n      process.exit(0);\n    });\n    process.on('SIGTERM', async () => {\n      console.log('SIGTERM received, shutting down server...');\n      await server.stop();\n      process.exit(0);\n    });\n  } catch (error) {\n    console.error('Failed to start MongoDB MCP Server:', error);\n    process.exit(1);\n  }\n}\n\nmain();\n\n// Alternative quick setup via CLI (recommended for initial setup):\n// npx mongodb-mcp-server setup\n// This command guides you through configuration and starts the server.","lang":"typescript","description":"This quickstart demonstrates how to programmatically start the MongoDB MCP Server, configure it with a connection string, and handle graceful shutdowns. It also mentions the easier CLI-based setup."},"warnings":[{"fix":"Review the official V2 release notes and migration guide upon release. Adjust programmatic imports and API calls as specified.","message":"Version 2 of `mongodb-mcp-server` will introduce breaking changes for programmatic 'library usage'. Users importing symbols directly for custom server implementations will need to adapt their code.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `MONGODB_URI` environment variable is set, or provide Atlas API credentials (`ATLAS_CLIENT_ID`, `ATLAS_PRIVATE_KEY`). For local Atlas tools, ensure Docker is installed and running.","message":"The server requires a MongoDB connection string or Atlas API credentials to start and function. Without proper configuration, the server will not launch. Docker is also a prerequisite for using local Atlas deployment tools.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set the `readOnly` configuration option to `true` when starting the server (`--read-only` CLI flag or `readOnly: true` in config). Implement strict MongoDB user permissions for the provided connection string to limit AI agent access.","message":"By default, the server may operate in read/write mode. Destructive operations like `delete-many`, `drop-collection`, and `drop-database` require explicit confirmation. To prevent unintended modifications, always consider starting the server in read-only mode, especially during initial exploration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Configure the `maxDocumentsPerQuery` option to limit the number of documents returned by a single query. Utilize the Performance Advisor tools exposed by the MCP server to identify and optimize slow queries and improve indexing.","message":"Queries performed by AI agents might return excessively large result sets, consuming significant resources.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify the `MONGODB_URI` environment variable or connection string provided in the server configuration. Ensure Atlas API credentials (client ID and private key) are correctly set up and have the necessary permissions. Test the connection string independently using `mongosh`.","cause":"Incorrect MongoDB connection string, invalid username/password, or missing Atlas API credentials.","error":"Failed to start MongoDB MCP Server: MongoServerError: Authentication failed."},{"fix":"Ensure Docker Desktop is installed and running on your system. Check Docker installation with `docker info`.","cause":"Docker is not running or not installed, which is required for features like local Atlas deployments.","error":"Error: Command failed with exit code 1: docker ps"},{"fix":"If write operations are intended, ensure the server is not started with the `readOnly: true` option. Verify the MongoDB user associated with the connection string has the required write roles (e.g., `readWrite` on the target database).","cause":"The MCP server is running in read-only mode, or the MongoDB user connected by the server lacks the necessary write privileges.","error":"Tool execution error: Insufficient permissions to perform write operation."}],"ecosystem":"npm"}