A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas.

• 🚀 Getting Started
  • Prerequisites
  • Setup
    • Quick Start
• 🛠️ Supported Tools
  • MongoDB Atlas Tools
  • MongoDB Database Tools
• 📄 Supported Resources
• ⚙️ Configuration
• 🚀 Deploy on Public Clouds
  • Azure Cloud
• 🤝 Contributing

• Node.js
  • At least 20.19.0
  • When using v22 then at least v22.12.0
  • Otherwise any version 23+

node -v

• A MongoDB connection string or Atlas API credentials, the Server will not start unless configured.
  • 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.

🔒 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:

• Windsurf: https://docs.windsurf.com/windsurf/mcp
• VSCode: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
• Claude Desktop: https://modelcontextprotocol.io/quickstart/user
• Cursor: https://docs.cursor.com/context/model-context-protocol

Default Safety Notice: All examples below include --readOnly by default to ensure safe, read-only access to your data. Remove --readOnly if you need to enable write operations.

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.

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"
      }
    }
  }
}

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

You can run the MongoDB MCP Server in a Docker container, which provides isolation and doesn't require a local Node.js installation.

You may provide either a MongoDB connection string OR Atlas API credentials:

docker run --rm -i \
  mongodb/mongodb-mcp-server:latest

# Set your credentials as environment variables first
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/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.

# 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.

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:password@cluster.mongodb.net/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"
      }
    }
  }
}

⚠️ Security Notice: This server now supports Streamable HTTP transport for remote connections. HTTP transport is NOT recommended for production use without implementing proper authentication and security measures.

Suggested Security Measures Examples:

• Implement authentication (e.g., API gateway, reverse proxy)
• Use HTTPS/TLS encryption
• Deploy behind a firewall or in private networks
• Implement rate limiting
• Never expose directly to the internet

For more details, see MCP Security Best Practices.

You can run the MongoDB MCP Server as an HTTP server instead of the default stdio transport. This is useful if you want to interact with the server over HTTP, for example from a web client or to expose the server on a specific port.

To start the server with HTTP transport, use the --transport http option:

npx -y mongodb-mcp-server@latest --transport http

By default, the server will listen on http://127.0.0.1:3000. You can customize the host and port using the --httpHost and --httpPort options:

npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --httpPort=8080

• --httpHost (default: 127.0.0.1): The host to bind the HTTP server.
• --httpPort (default: 3000): The port number for the HTTP server.

Note: The default transport is stdio, which is suitable for integration with most MCP clients. Use http transport if you need to interact with the server over HTTP.

• atlas-list-orgs - Lists MongoDB Atlas organizations
• atlas-list-projects - Lists MongoDB Atlas projects
• atlas-create-project - Creates a new MongoDB Atlas project
• atlas-list-clusters - Lists MongoDB Atlas clusters
• atlas-inspect-cluster - Inspect a specific MongoDB Atlas cluster
• atlas-create-free-cluster - Create a free MongoDB Atlas cluster
• atlas-connect-cluster - Connects to MongoDB Atlas cluster
• atlas-inspect-access-list - Inspect IP/CIDR ranges with access to MongoDB Atlas clusters
• atlas-create-access-list - Configure IP/CIDR access list for MongoDB Atlas clusters
• atlas-list-db-users - List MongoDB Atlas database users
• atlas-create-db-user - Creates a MongoDB Atlas database user
• atlas-list-alerts - List MongoDB Atlas Alerts for a Project
• atlas-get-performance-advisor - Gets Atlas Performance Advisor recommendations (index suggestions, drop index suggestions, schema suggestions, slow query logs)

NOTE: atlas tools are only available when you set credentials on configuration section.

• atlas-local-list-deployments - Lists MongoDB Atlas Local deployments
• atlas-local-create-deployment - Creates a MongoDB Atlas Local deployment
• atlas-local-connect-deployment - Connects to a MongoDB Atlas Local deployment
• atlas-local-delete-deployment - Deletes a MongoDB Atlas Local deployment

• connect - Connect to a MongoDB instance
• find - Run a find query against a MongoDB collection. The number of documents returned is limited by the limit parameter and the server's maxDocumentsPerQuery configuration, whichever is smaller. The total size of the returned documents is also limited by the responseBytesLimit parameter and the server's maxBytesPerQuery configuration, whichever is smaller.
• aggregate - Run an aggregation against a MongoDB collection. The number of documents returned is limited by the server's maxDocumentsPerQuery configuration. The total size of the returned documents is also limited by the responseBytesLimit parameter and the server's maxBytesPerQuery configuration, whichever is smaller.
• count - Get the number of documents in a MongoDB collection
• insert-many - Insert multiple documents into a MongoDB collection
• create-index - Create an index for a MongoDB collection
• update-many - Update multiple documents in a MongoDB collection
• rename-collection - Rename a MongoDB collection
• delete-many - Delete multiple documents from a MongoDB collection
• drop-collection - Remove a collection from a MongoDB database
• drop-database - Remove a MongoDB database
• list-databases - List all databases for a MongoDB connection
• list-collections - List all collections for a given database
• collection-indexes - Describe the indexes for a collection
• collection-schema - Describe the schema for a collection
• collection-storage-size - Get the size of a collection in MB
• db-stats - Return statistics about a MongoDB database
• export - Export query or aggregation results to EJSON format. Creates a uniquely named export accessible via the exported-data resource.

• 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 URI config://config.
• debug - Debugging information for MongoDB connectivity issues. Tracks the last connectivity attempt and error information. The resource can be accessed under URI debug://mongodb.
• exported-data - A resource template to access the data exported using the export tool. The template can be accessed under URI exported-data://{exportName} where exportName is the unique name for an export generated by the export tool.

For complete configuration details (all options, security practices, Atlas setup, examples), see the dedicated documentation in CONFIGURATION.md.

You can deploy the MongoDB MCP Server to your preferred cloud provider using the deployment assets under deploy/. Each guide explains the prerequisites, configuration, and automation scripts that streamline the rollout.

For detailed Azure instructions, see deploy/azure/README.md.

Interested in contributing? Great! Please check our Contributing Guide for guidelines on code contributions, standards, adding new tools, and troubleshooting information.