Mongodb Mcp Server

[](https://insiders.vscode.dev/redirect/mcp/install?name=mongodb&inputs=%5B%7B%22id%22%3A%22connectionstring%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22MongoDB%20connection%20string%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mongodb-mcp-server%22%2C%22--readOnly%22%5D%2C%22env%22%3A%7B%22MDBMCPCONNECTIONSTRING%22%3A%22%24%7Binput%3Aconnection_string%7D%22%7D%7D) [](https://cursor.com/en-US/install-mcp?name=MongoDB&config=eyJjb21tYW5kIjoibnB4IC15IG1vbmdvZGItbWNwLXNlcnZlciAtLXJlYWRPbmx5In0%3D)

MongoDB MCP Server

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

📚 Table of Contents

• [🚀 Getting Started](#getting-started)
• [Prerequisites](#prerequisites)
• [Setup](#setup)
• [Quick Start](#quick-start)
• [🛠️ Supported Tools](#supported-tools)
• [MongoDB Atlas Tools](#mongodb-atlas-tools)
• [MongoDB Database Tools](#mongodb-database-tools)
• [MongoDB Assistant Tools](#mongodb-assistant-tools)
• [📄 Supported Resources](#supported-resources)
• [⚙️ Configuration](#configuration)
• [Configuration Options](#configuration-options)
• [Atlas API Access](#atlas-api-access)
• [Configuration Methods](#configuration-methods)
• [Environment Variables](#environment-variables)
• [Command-Line Arguments](#command-line-arguments)
• [MCP Client Configuration](#mcp-configuration-file-examples)
• [Proxy Support](#proxy-support)
• [🚀 Deploy on Public Clouds](#deploy-on-public-clouds)
• [Azure Cloud](#azure)
• [🤝 Contributing](#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](#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](#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](#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](#environment-variables) for platform-specific instructions.

• For a complete list of configuration options see [Configuration Options](#configuration-options)
• To configure your Atlas Service Accounts credentials please refer to [Atlas API Access](#atlas-api-access)
• Connection String via environment variables in the MCP file [example](#connection-string-with-environment-variables)
• Atlas API credentials via environment variables in the MCP file [example](#atlas-api-credentials-with-environment-variables)

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 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](#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](#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: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"
      }
    }
  }
}

Option 5: Running as an HTTP Server

> ⚠️ 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.

Option 6: Copilot CLI

You can use the Copilot CLI to interactively add the MCP server:

/mcp add

Alternatively, create or edit the configuration file ~/.copilot/mcp-config.json and add:

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}

For more information, see the Copilot CLI documentation.

Option 7: OpenCode

Create or edit your OpenCode config file (~/.config/opencode/opencode.json or project-specific ./opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "MongoDB": {
      "type": "local",
      "command": ["npx", "-y", "mongodb-mcp-server@latest", "--readOnly"],
      "enabled": true,
      "environment": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}

For more information about configuring OpenCode as an MCP client, including the expected syntax and options, see the OpenCode MCP servers documentation.

🛠️ Supported Tools

Tool List

MongoDB Database Tools

• aggregate - Run an aggregation against a MongoDB collection
• aggregate-db - Run an aggregation against a MongoDB database
• collection-indexes - Describe the indexes for a collection
• collection-schema - Describe the schema for a collection
• collection-storage-size - Gets the size of the collection
• connect - Connect to a MongoDB instance
• count - Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parameter
• create-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 collection
• db-stats - Returns statistics that reflect the use state of a single database
• delete-many - Removes all documents that match the filter from a MongoDB collection
• 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 files
• drop-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 method
• export - Export a query or aggregation results in the specified EJSON format.
• find - Run a find query against a MongoDB collection
• insert-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 database
• list-databases - List all databases for a MongoDB connection
• mongodb-logs - Returns the most recent logged mongod events
• rename-collection - Renames a collection in a MongoDB database
• switch-connection - Switch to a different MongoDB connection
• update-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
• 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. 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 user
• atlas-create-free-cluster - Create a free MongoDB Atlas cluster
• atlas-create-project - Create a MongoDB Atlas project
• atlas-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 logs
• atlas-inspect-access-list - Inspect Ip/CIDR ranges with access to your MongoDB Atlas clusters.
• atlas-inspect-cluster - Inspect metadata of a MongoDB Atlas cluster
• atlas-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 clusters
• atlas-list-db-users - List MongoDB Atlas database users
• atlas-list-orgs - List MongoDB Atlas organizations
• atlas-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, provide clusterName — the load runs asynchronously and the response includes a jobId and initial state. To check progress, call this tool again with jobId (sample dataset loads typically take 1–5 minutes). State can be WORKING, COMPLETED, or FAILED.
• `at

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mongodb-js
• Source: mongodb-js/mongodb-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.