Registry / database / mongodb-mcp-server

mongodb-mcp-server

JSON →
library0.1.1jsnpmunverified

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.

npm install mongodb-mcp-server
INSTALL
IMPORT
SIG · MONGODB-MCP-SERVER
M
mongodb-mcp-server
databasejavascriptv0.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer
import { startServer } from 'mongodb-mcp-server';
Primary function for programmatically starting the MCP server. Most common usage is via `npx` or AI client configuration, but programmatic control is available.
Config
import { type Config } from 'mongodb-mcp-server';
import { Config } from 'mongodb-mcp-server';
Represents the server's configuration interface, useful for type-checking when creating custom configurations. Imported as a type.
Server
import { Server } from 'mongodb-mcp-server';
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.

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.

import { startServer } from 'mongodb-mcp-server'; // To run the server programmatically, you must provide a MongoDB connection string. // This can be via environment variables (MONGODB_URI, ATLAS_CLIENT_ID, ATLAS_PRIVATE_KEY) // or passed directly in the configuration object. // Ensure you have a MongoDB connection string set as an environment variable // or replace process.env.MONGODB_URI with your actual connection string. // For Atlas API credentials, set ATLAS_CLIENT_ID and ATLAS_PRIVATE_KEY. const connectionString = process.env.MONGODB_URI ?? 'mongodb://localhost:27017/mcp-db'; const serverConfig = { connectionString: connectionString, port: 3000, readOnly: false, // Set to true to disable write operations logLevel: 'info' // 'debug', 'info', 'warn', 'error' }; async function main() { try { console.log('Starting MongoDB MCP Server...'); const server = await startServer(serverConfig); console.log(`MongoDB MCP Server listening on port ${serverConfig.port}`); // Example: Graceful shutdown process.on('SIGINT', async () => { console.log('SIGINT received, shutting down server...'); await server.stop(); process.exit(0); }); process.on('SIGTERM', async () => { console.log('SIGTERM received, shutting down server...'); await server.stop(); process.exit(0); }); } catch (error) { console.error('Failed to start MongoDB MCP Server:', error); process.exit(1); } } main(); // Alternative quick setup via CLI (recommended for initial setup): // npx mongodb-mcp-server setup // This command guides you through configuration and starts the server.
mongodb-mcp-server --version
Debug
Known issues
breakingVersion 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.
fix
Review the official V2 release notes and migration guide upon release. Adjust programmatic imports and API calls as specified.
affects: >=2.0.0
gotchaThe 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.
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.
affects: >=1.0.0
gotchaBy 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.
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.
affects: >=1.0.0
gotchaQueries performed by AI agents might return excessively large result sets, consuming significant resources.
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.
affects: >=1.0.0
Errors
Common errors & fixes
Failed to start MongoDB MCP Server: MongoServerError: Authentication failed.
Incorrect MongoDB connection string, invalid username/password, or missing Atlas API credentials.
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`.
Error: Command failed with exit code 1: docker ps
Docker is not running or not installed, which is required for features like local Atlas deployments.
fix
Ensure Docker Desktop is installed and running on your system. Check Docker installation with `docker info`.
Tool execution error: Insufficient permissions to perform write operation.
The MCP server is running in read-only mode, or the MongoDB user connected by the server lacks the necessary write privileges.
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).
Upgrade
Version history
0.1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
mongodb-mcp-server — npm install mongodb-mcp-server · libregistry