mongodb-mcp-server

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 install mongodb-atlas.
• Claude: marketplace
• Codex: Open /plugins and install mongodb-atlas.
• GitHub Copilot CLI: Run copilot plugin install mongodb-atlas.
• Grok: Open /marketplace in Grok Build and install mongodb-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 /plugins and install mongodb.
• GitHub Copilot CLI: Run copilot plugin install mongodb.
• Grok: Open /marketplace in Grok Build and install mongodb.

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
  • Prerequisites
  • Manual Setup
• 🛠️ 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.

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:

• Devin AI
• Claude Desktop & Web
• Cursor
• Codex
• Other AI clients

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: 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-remote stdio server, which you can authenticate into using the static MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET environment 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"
      }
    }
  }
}