MongoDB MCP Server

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

📚 Table of Contents

• 🚀 Getting Started
  • Prerequisites
  • Setup
    • Quick Start
• 🛠️ Supported Tools
  • MongoDB Atlas Tools
  • MongoDB Database Tools
  • MongoDB Assistant Tools
• 📄 Supported Resources
• ⚙️ Configuration
  • Configuration Options
  • Atlas API Access
  • Configuration Methods
    • Environment Variables
    • Command-Line Arguments
    • MCP Client Configuration
    • Proxy Support
• 🚀 Deploy on Public Clouds
  • Azure Cloud
• 🤝 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.

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

Setup

Quick Start

🔒 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
• Copilot CLI: https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli
• Opencode CLI: https://opencode.ai/docs/mcp-servers

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.

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

# Then start the