MongoDB MCP Server
A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas.
Quick Start
Using the official MongoDB plugins for AI agents
MongoDB MCP Server comes bundled with the official MongoDB plugins for AI agents. The following plugins are available:
mongodb-atlas — connects to the MongoDB-hosted Atlas MCP server over OAuth. This does not require you to run anything locally, and is the recommended way to connect to MongoDB Atlas from your AI agent:
- Cursor: marketplace
- VSCode: Open the Extensions view (
⇧⌘X/Ctrl+Shift+X), search for@agentPlugins, and installmongodb-atlas. - Claude: marketplace
- Codex: Open
/pluginsand installmongodb-atlas. - GitHub Copilot CLI: Run
copilot plugin install mongodb-atlas. - Grok: Open
/marketplacein Grok Build and installmongodb-atlas.
mongodb — runs the MongoDB MCP server locally and connects to any self-managed deployment:
- Cursor: marketplace
- Claude: marketplace
- Gemini: marketplace
- Codex: Run
codex plugin marketplace add mongodb/agent-skills, then open/pluginsand installmongodb. - GitHub Copilot CLI: Run
copilot plugin install mongodb. - Grok: Open
/marketplacein Grok Build and installmongodb.
Using the setup script
You can manually set up the local MCP server by running the following command:
npx -y mongodb-mcp-server@latest setup
This will guide you through an interactive setup process, including configuring your MongoDB connection string or Atlas API credentials.
For more advanced setup options, see the Manual Setup section below.
Using the MongoDB MCP Server setup skill
You can add and use the MongoDB MCP Server setup skill to configure your local MCP server using an AI agent.
npx skills add https://github.com/mongodb/agent-skills --skill mongodb-mcp-setup
Using manual configuration
See Manual Setup for instructions on how to manually configure the MongoDB MCP Server.
📚 Table of Contents
- 🚀 Getting Started
- 🛠️ Supported Tools
- 📄 Supported Resources
- ⚙️ Configuration
- 🚀 Deploy on Public Clouds
- 🤝 Contributing
Prerequisites
[!NOTE] Node 20.x support is deprecated and will be removed in a future release. Please upgrade to Node 22.13 or later. See https://nodejs.org/en/blog/migrations/v20-to-v22 for migration details.
-
Node.js
- At least v22.13.0. Check with
node -v.
- At least v22.13.0. Check with
-
A MongoDB connection string or Atlas API credentials.
- Service Accounts Atlas API credentials are required to use the Atlas tools. You can create a service account in MongoDB Atlas and use its credentials for authentication. See Atlas API Access for more details.
- If you have a MongoDB connection string, you can use it directly to connect to your MongoDB instance.
Manual Setup
🔒 Security Recommendation 1: When using Atlas API credentials, be sure to assign only the minimum required permissions to your service account. See Atlas API Permissions for details.
🔒 Security Recommendation 2: For enhanced security, we strongly recommend using environment variables to pass sensitive configuration such as connection strings and API credentials instead of command line arguments. Command line arguments can be visible in process lists and logged in various system locations, potentially exposing your secrets. Environment variables provide a more secure way to handle sensitive information.
Most MCP clients require a configuration file to be created or modified to add the MCP server.
Note: The configuration file syntax can be different across clients. Please refer to the following links for the latest expected syntax:
Default Safety Notice: All examples below include
--readOnlyby default to ensure safe, read-only access to your data. Remove--readOnlyif you need to enable write operations.
Option 1: Connection String
You can pass your connection string via environment variables, make sure to use a valid username and password.
{
"mcpServers": {
"MongoDB": {
"command": "npx",
"args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
"env": {
"MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
}
}
}
}
NOTE: The connection string can be configured to connect to any MongoDB cluster, whether it's a local instance or an Atlas cluster.
Option 2: Connect to the MongoDB Atlas-Managed MCP Server
When working with MongoDB Atlas, the recommended approach is to install the mongodb-atlas plugin for your AI agent, which handles OAuth authentication automatically.
For manual configuration, see the client-specific instructions for setting up the Atlas Remote MCP server with OAuth. Alternatively, you can connect using the mongodb-atlas-mcp-remote package with Service Account credentials — see the package README for setup instructions.
Note: You cannot authenticate to the remote MongoDB MCP server using a static API key over HTTP. You must either:
- Use a client that supports the OAuth flow.
- Use the
mongodb-atlas-mcp-remotestdio server, which you can authenticate into using the staticMDB_MCP_API_CLIENT_IDandMDB_MCP_API_CLIENT_SECRETenvironment variables.
To connect with the mongodb-atlas-mcp-remote stdio server using Service Account credentials, add it to your client's MCP configuration:
{
"mcpServers": {
"mongodb-atlas-mcp-remote": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mongodb-atlas-mcp-remote@latest"],
"env": {
"MDB_MCP_API_CLIENT_ID": "$CLIENT_ID",
"MDB_MCP_API_CLIENT_SECRET": "$SECRET"
}
}
}
}
Option 3: Atlas API Credentials
Use your Atlas API Service Accounts credentials. Must follow all the steps in Atlas API Access section.
{
"mcpServers": {
"MongoDB": {
"command": "npx",
"args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
"env": {
"MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
"MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
}
}
}
}
Option 4: Standalone Service using environment variables and command line arguments
You can source environment variables defined in a config file or explicitly set them like we do in the example below and run the server via npx.
# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
# Then start the server
npx -y mongodb-mcp-server@latest --readOnly
💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.
- For a complete list of configuration options see Configuration Options
- To configure your Atlas Service Accounts credentials please refer to Atlas API Access
- Connection String via environment variables in the MCP file example
- Atlas API credentials via environment variables in the MCP file example
Option 5: Using Docker
You can run the MongoDB MCP Server in a Docker container, which provides isolation and doesn't require a local Node.js installation.
Run with Environment Variables
You may provide either a MongoDB connection string OR Atlas API credentials:
Option A: No configuration
docker run --rm -i \
mongodb/mongodb-mcp-server:latest
Option B: With MongoDB connection string
# Set your credentials as environment variables first
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:[email protected]/myDatabase"
# Then start the docker container
docker run --rm -i \
-e MDB_MCP_CONNECTION_STRING \
-e MDB_MCP_READ_ONLY="true" \
mongodb/mongodb-mcp-server:latest
💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.
Option C: With Atlas API credentials
# Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
# Then start the docker container
docker run --rm -i \
-e MDB_MCP_API_CLIENT_ID \
-e MDB_MCP_API_CLIENT_SECRET \
-e MDB_MCP_READ_ONLY="true" \
mongodb/mongodb-mcp-server:latest
💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.
Docker in MCP Configuration File
Without options:
{
"mcpServers": {
"MongoDB": {
"command": "docker",
"args": [
"run",
"--rm",
"-e",
"MDB_MCP_READ_ONLY=true",
"-i",
"mongodb/mongodb-mcp-server:latest"
]
}
}
}
With connection string:
{
"mcpServers": {
"MongoDB": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"MDB_MCP_CONNECTION_STRING",
"-e",
"MDB_MCP_READ_ONLY=true",
"mongodb/mongodb-mcp-server:latest"
],
"env": {
"MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:[email protected]/myDatabase"
}
}
}
}
With Atlas API credentials:
{
"mcpServers": {
"MongoDB": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"MDB_MCP_READ_ONLY=true",
"-e",
"MDB_MCP_API_CLIENT_ID",
"-e",
"MDB_MCP_API_CLIENT_SECRET",
"mongodb/mongodb-mcp-server:latest"
],
"env": {
"MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
"MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
}
}
}
}
HTTP Compatibility
For custom HTTP clients and hosts, see the library guide's HTTP compatibility requirements, including protocol headers, redirects, legacy sessions, and request size limits.
🛠️ Supported Tools
Tool List
MongoDB Database Tools
aggregate- Run an aggregation against a MongoDB collectionaggregate-db- Run an aggregation against a MongoDB databasecollection-indexes- Describe the indexes for a collectioncollection-schema- Describe the schema for a collectioncollection-storage-size- Gets the size of the collectionconnect- Connect to a MongoDB instancecount- Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parametercreate-collection- Creates a new collection in a database. If the database doesn't exist, it will be created automatically.create-index- Create an index for a collectiondb-stats- Returns statistics that reflect the use state of a single databasedelete-many- Removes all documents that match the filter from a MongoDB collectiondisconnect- Close a MongoDB connection and revoke its connectionId.drop-collection- Removes a collection or view from the database. The method also removes any indexes associated with the dropped collection.drop-database- Removes the specified database, deleting the associated data filesdrop-index- Drop an index for the provided database and collection.explain- Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated methodexport- Export a query or aggregation results in the specified EJSON format.find- Run a find query against a MongoDB collectioninsert-many- Insert an array of documents into a MongoDB collection. If the list of documents is above com.mongodb/maxRequestPayloadBytes, consider inserting them in batches.list-collections- List all collections for a given databaselist-connections- List the active MongoDB connections and their connectionIds. Use this to find a connectionId established earlier.list-databases- List all databases for a MongoDB connectionmongodb-logs- Returns the most recent logged mongod eventsrename-collection- Renames a collection in a MongoDB databaseupdate-many- Updates all documents that match the specified filter for a collection. If the list of documents is above com.mongodb/maxRequestPayloadBytes, consider updating them in batches.
MongoDB Atlas Tools
atlas-connect-cluster- Connect to MongoDB Atlas cluster and get back a connectionId to pass to the other MongoDB tools. Each call establishes a new, independent connection — multiple connections can be active at the same time.atlas-create-access-list- Allow Ip/CIDR ranges to access your MongoDB Atlas clusters.atlas-create-cluster- Create a MongoDB Atlas cluster (M10–M80, replica set or single shard). Compute autoscaling is enabled by default: min instance size is set to the selected instance size, max is set two tiers above. Disk autoscaling is always enabled. Encryption at rest with customer-managed keys (CMK) is supported, the CMK provider must already have a valid encryption at rest configuration in the project. The tool returns immediately, use the atlas-inspect-cluster tool to poll the cluster state for readiness (state: IDLE). Connection strings are unavailable until the cluster reaches IDLE state.atlas-create-db-user- Create an MongoDB Atlas database useratlas-create-free-cluster- Create a free MongoDB Atlas clusteratlas-create-project- Create a MongoDB Atlas projectatlas-get-performance-advisor- Get MongoDB Atlas performance advisor recommendations and suggestions, which includes the operations: suggested indexes, drop index suggestions, schema suggestions, and a sample of the most recent (max 50) slow query logsatlas-get-regions- List supported MongoDB Atlas regions for a cloud provider.atlas-inspect-access-list- Inspect Ip/CIDR ranges with access to your MongoDB Atlas clusters.atlas-inspect-cluster- Inspect metadata of a MongoDB Atlas clusteratlas-list-alerts- List triggered alerts for a MongoDB Atlas project. These are alerts Atlas has raised, not the alert configurations that define them. Defaults to OPEN alerts; set status to TRACKING or CLOSED to see others.atlas-list-clusters- List MongoDB Atlas clustersatlas-list-db-users- List MongoDB Atlas database usersatlas-list-orgs- List MongoDB Atlas organizationsatlas-list-projects- List MongoDB Atlas projects.atlas-load-sample-dataset- Load a MongoDB sample dataset into an Atlas cluster, or check the status of a previously-initiated load. To start a new load, provideclusterName— the load runs asynchronously and the response includes ajobIdand initial state. To check progress, call this tool again withjobId(sample dataset loads typically take 1–5 minutes). State can be WORKING, COMPLETED, or FAILED.
NOTE: atlas tools are only available when you set credentials on configuration section.
MongoDB Atlas Local Tools
atlas-local-connect-deployment- Connect to a MongoDB Atlas Local deployment and get back a connectionId to pass to the other MongoDB toolsatlas-local-create-deployment- Create a MongoDB Atlas local deployment. Default image is latest. When the user does not specify an image tag, inform them that latest is used by default and provide this link for more information: https://hub.docker.com/r/mongodb/mongodb-atlas-localatlas-local-delete-deployment- Delete a MongoDB Atlas local deploymentatlas-local-list-deployments- List MongoDB Atlas local deployments
MongoDB Assistant Tools
list-knowledge-sources- List available data sources in the MongoDB Assistant knowledge base. Use this to explore available data sources or to find search filter parameters to use in search-knowledge.search-knowledge- Search for information in the MongoDB Assistant knowledge base. This includes official documentation, curated expert guidance, and other resources provided by MongoDB. Supports filtering by data source and version.
📄 Supported Resources
config- Server configuration, supplied by the user either as environment variables or as startup arguments with sensitive parameters redacted. The resource can be accessed under URIconfig://config.debug- Debugging information for MongoDB connectivity issues. Tracks the last connectivity attempt and error information. The resource can be accessed under URIdebug://mongodb.exported-data- A resource template to access the data exported using the export tool. The template can be accessed under URIexported-data://{exportName}whereexportNameis the unique name for an export generated by the export tool.
Configuration
🔒 Security Best Practice: We strongly recommend using environment variables for sensitive configuration such as API credentials (
MDB_MCP_API_CLIENT_ID,MDB_MCP_API_CLIENT_SECRET) and connection strings (MDB_MCP_CONNECTION_STRING) instead of command-line arguments. Environment variables are not visible in process lists and provide better security for your sensitive data.
The MongoDB MCP Server can be configured using multiple methods, with the following precedence (highest to lowest):
- Command-line arguments
- Environment variables
- Configuration File