---
title: "MongoDB MCP Server: Official Setup, Read-Only Mode, Atlas"
url: "https://mcpshelf.co/servers/mongodb"
description: "MongoDB's own MCP server lets Claude, Cursor or Copilot query collections, read schemas and manage Atlas. The setup command, read-only mode, safe defaults."
updated: "2026-11-10"
site: "MCP Shelf"
---

# MongoDB MCP Server

> Query, inspect and manage MongoDB databases and Atlas clusters, read-only if you like.

Source: https://mcpshelf.co/servers/mongodb  
Markdown: https://mcpshelf.co/servers/mongodb.md  
Generated: 2026-11-22T13:57:57.177Z

## Facts

- **Name:** MongoDB MCP Server
- **Tagline:** Query, inspect and manage MongoDB databases and Atlas clusters, read-only if you like.
- **Description:** MongoDB MCP Server is MongoDB's official server that lets an AI assistant query and inspect MongoDB databases and manage Atlas clusters, users and access lists, with a read-only mode.
- **Repository:** https://github.com/mongodb-js/mongodb-mcp-server
- **Package:** mongodb-mcp-server 3.3.0 (npm)
- **Install:** `npx -y mongodb-mcp-server@latest setup`
- **Transport:** stdio (local)
- **Auth:** No required keys or settings listed
- **Tools exposed:** 20: `connect`, `disconnect`, `list-connections`, `list-databases`, `list-collections`, `collection-schema`, `collection-indexes`, `collection-storage-size`, `db-stats`, `find`, `count`, `aggregate`, `aggregate-db`, `explain`, `export`, `mongodb-logs`, `atlas-local-list-deployments`, `atlas-local-connect-deployment`, `list-knowledge-sources`, `search-knowledge`
- **Category:** Databases and data (https://mcpshelf.co/categories/databases)
- **Stats:** 1.2K GitHub stars, 83.3K downloads a week, last commit 28 Oct 2026, 0 upvotes on MCP Shelf
- **Install check:** Needs your setup first
- **Listed:** 2026-11-10
- **Page updated:** 2026-11-10

## Full description

### What is MongoDB MCP Server?

**MongoDB MCP Server is MongoDB's official server that lets an AI assistant query and inspect MongoDB databases and manage Atlas clusters, users and access lists, with a read-only mode.**

This is the server MongoDB itself maintains. Give it a connection string and the assistant can list databases and collections, sample a collection's schema, run find and aggregation queries, check indexes and explain why a query is slow. Add Atlas service account credentials as well and it can list projects and clusters, create a free cluster, manage database users and the IP access list, and read the Performance Advisor.

The README's own examples all start the server with --readOnly, and that is the right way to begin: only read, connect and metadata tools load, so nothing can be inserted, updated or dropped. Even with writes on, dropping a database, a collection or an index and deleting documents ask you to confirm first by default, in clients that support confirmation prompts.

|  |  |
| --- | --- |
| Made by | MongoDB (mongodb-js/mongodb-mcp-server) |
| GitHub | https://github.com/mongodb-js/mongodb-mcp-server |
| Licence | Apache-2.0 |
| npm package | [mongodb-mcp-server](https://www.npmjs.com/package/mongodb-mcp-server) 3.3.0 (9 Nov 2026) |
| GitHub stars | 1.2K |
| Downloads | 83.3K a week |
| Last commit | 28 Oct 2026 |
| Tools | 20 |
| Runs on | Your computer |
| Install check | Needs your setup first |
| Category | [Databases and data](https://mcpshelf.co/categories/databases) |
| Works with | Claude Code, Cursor, Claude Desktop, VS Code, Codex, Windsurf |
| Setup checked | 10 Nov 2026 |
| Page updated | 10 Nov 2026 |

**Our check:** It needs something our Linux test machine does not have (an account, a desktop app, a Mac or a running service), so on 10 Nov 2026 we read its tools from the source code instead of running this config.

#### Try asking MongoDB MCP Server

- "Which collections are in my database, and what does a typical document in users look like?"
- "How many orders were placed per day last week?"
- "Explain why this find query is slow and suggest an index."

#### MCP Shelf take

> MongoDB needs something our Linux test machine does not have (an account, an app or a service), so on 10 Nov 2026 we read its source and counted 20 tools. All 20 only read, so it cannot change anything on its own. It sits 7th of 10 in its category on our shelf by GitHub stars (1.2K, with 83.3K downloads a week).

— MCP Shelf tests (numbers from our own runs), tested on 10 Nov 2026

### What tools does MongoDB MCP Server have?

We listed 20 tools on 10 Nov 2026. Every one of them only reads.

| Tool | Kind | What it is for |
| --- | --- | --- |
| `connect` | reads | Opens a connection from a connection string and returns an id that the other tools use. |
| `disconnect` | reads | Closes a connection and retires its id. |
| `list-connections` | reads | Shows the open connections and their ids, so the model can reuse one. |
| `list-databases` | reads | Lists the databases on the connected deployment. |
| `list-collections` | reads | Lists the collections in one database. |
| `collection-schema` | reads | Samples a collection and describes the fields and types it finds. |
| `collection-indexes` | reads | Lists a collection's indexes. |
| `collection-storage-size` | reads | Reports how much disk a collection uses. |
| `db-stats` | reads | Returns size and usage statistics for a database. |
| `find` | reads | Runs a find query with a filter, projection, sort and limit. |
| `count` | reads | Counts the documents that match an optional filter. |
| `aggregate` | reads | Runs an aggregation pipeline on a collection. |
| `aggregate-db` | reads | Runs a database-level aggregation, such as $currentOp or $documents. |
| `explain` | reads | Shows the plan the query optimiser picked for a find, count or aggregation, so slow queries can be spotted. |
| `export` | reads | Saves the results of a query or pipeline as EJSON that the client can read as a resource. |
| `mongodb-logs` | reads | Reads the most recent mongod log events. |
| `atlas-local-list-deployments` | reads | Lists the Atlas Local deployments running in Docker on your machine. |
| `atlas-local-connect-deployment` | reads | Connects to an Atlas Local deployment and returns a connection id. |
| `list-knowledge-sources` | reads | Lists the sources in the MongoDB Assistant knowledge base. |
| `search-knowledge` | reads | Searches MongoDB's documentation and expert guidance, filtered by source and version. |

#### Tool groups

| Group | Covers |
| --- | --- |
| `Database tools` | Connections, databases, collections, schema, indexes, find, aggregate, explain, export and logs, plus inserts, updates, deletes and drops when read-only is off. Need a connection string. |
| `Atlas tools` | About 22 atlas-* tools: organisations, projects and clusters, free and dedicated cluster creation, upgrades and pause or resume, database users, the IP access list, alerts, the Performance Advisor, sample data and Stream Processing. Only load with Atlas service account credentials. |
| `Atlas Local tools` | List, create, connect to and delete local Atlas deployments in Docker. |
| `MongoDB Assistant tools` | list-knowledge-sources and search-knowledge, over MongoDB's own docs and guidance. |

### How do I install MongoDB MCP Server?

#### Install steps from the MongoDB MCP Server README

Copied from the project's [README on GitHub](https://github.com/mongodb-js/mongodb-mcp-server#readme) on 21 Nov 2026 under its Apache-2.0 licence.

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

###### 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](https://cursor.com/marketplace/mongodb/mongodb-atlas)
- VSCode: Open the Extensions view (`⇧⌘X` / `Ctrl+Shift+X`), search for `@agentPlugins`, and install `mongodb-atlas`.
- Claude: [marketplace](https://claude.com/plugins/mongodb-atlas)
- 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](https://cursor.com/marketplace/mongodb/mongodb)
- Claude: [marketplace](https://claude.com/plugins/mongodb)
- Gemini: [marketplace](https://geminicli.com/extensions/?name=mongodbagent-skills)
- 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.

#### What you need first

- Node.js 22.13 or newer (20.19 still runs but is deprecated)
- A MongoDB connection string, or Atlas service account credentials for the Atlas tools

#### Fastest way: one command

```bash
npx -y mongodb-mcp-server@latest setup
```

The README's setup script walks you through the connection string or Atlas credentials and writes the config for your client. MongoDB's own plugins are the other quick route: mongodb for a local server, mongodb-atlas for the hosted Atlas server over OAuth, in the Claude, Cursor, VS Code and Codex plugin directories.

#### Claude Code

Where: Your terminal, in the project folder

```bash
claude mcp add mongodb -e MDB_MCP_CONNECTION_STRING=mongodb://localhost:27017/myDatabase -- npx -y mongodb-mcp-server@latest --readOnly
```

Or install MongoDB's plugin from the Claude plugin directory: mongodb runs this server locally, mongodb-atlas connects to the Atlas-hosted server with OAuth.

#### Cursor

Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

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

Cursor's marketplace has both MongoDB plugins, mongodb and mongodb-atlas, which set this up for you.

#### Claude Desktop

Where: claude_desktop_config.json (Settings → Developer → Edit Config)

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

#### VS Code

Where: .vscode/mcp.json in your project

```json
{
  "servers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server@latest",
        "--readOnly"
      ],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}
```

#### Codex

Where: ~/.codex/config.toml, shared by the Codex CLI, IDE extension and ChatGPT desktop app

```
[mcp_servers.mongodb]
command = "npx"
args = ["-y", "mongodb-mcp-server@latest", "--readOnly"]

[mcp_servers.mongodb.env]
MDB_MCP_CONNECTION_STRING = "mongodb://localhost:27017/myDatabase"
```

Or run: `codex mcp add mongodb --env MDB_MCP_CONNECTION_STRING=mongodb://localhost:27017/myDatabase -- npx -y mongodb-mcp-server@latest --readOnly`

#### Windsurf

Where: ~/.codeium/windsurf/mcp_config.json

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

#### ChatGPT

Where: Not supported

ChatGPT on the web only takes servers by URL. This one runs on your computer, so use the ChatGPT desktop app with the Codex config, or Codex itself, where the mongodb-atlas plugin is also in /plugins.

Put your own connection string in MDB_MCP_CONNECTION_STRING, keep it in env rather than in args, and remove --readOnly only once you want the assistant to change data.

Checked against the project's own install docs on 10 Nov 2026: https://github.com/mongodb-js/mongodb-mcp-server#readme, https://www.mongodb.com/docs/mcp-server/get-started/, https://github.com/mongodb-js/mongodb-mcp-server/blob/main/packages/mongodb-atlas-mcp-remote/README.md

### How do I configure MongoDB MCP Server?

| Setting | Kind | Required | What it does |
| --- | --- | --- | --- |
| `MDB_MCP_CONNECTION_STRING` | env | no | The connection string the database tools use. Needed unless you only use Atlas tools. Keep it in env, not on the command line. Example: `mongodb+srv://user:pass@cluster0.example.mongodb.net/myDatabase` |
| `--readOnly` | flag | no | Loads only read, connect and metadata tools. Every example in the README uses it. Also MDB_MCP_READ_ONLY=true. Example: `--readOnly` |
| `MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET` | env | no | An Atlas service account's credentials. They switch on the Atlas tools; give the account the narrowest role that covers what you need. |
| `MDB_MCP_DISABLED_TOOLS` | env | no | Comma-separated tool names, operation types (create, update, delete, read, metadata) or categories (atlas, mongodb) to leave out. Example: `atlas,delete` |
| `MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` | env | no | Which tools ask you before they run, in clients that support elicitation. By default the drops, delete-many, Atlas user and access list creation and the Stream Processing changes; pipelines with $out or $merge always ask. |
| `MDB_MCP_INDEX_CHECK` | env | no | When true, refuses queries that would scan a whole collection without an index. Example: `true` |
| `MDB_MCP_MAX_DOCUMENTS_PER_QUERY` | env | no | Caps the documents one find or aggregate returns. Default 100; MDB_MCP_MAX_BYTES_PER_QUERY caps the size, 16 MB by default. Example: `100` |
| `MDB_MCP_TELEMETRY` | env | no | Set to disabled to turn off the usage telemetry the server sends to MongoDB. Example: `disabled` |
| `MDB_MCP_TRANSPORT` | env | no | stdio, the default, or http. The HTTP server binds to 127.0.0.1:3000 unless you change MDB_MCP_HTTP_HOST and MDB_MCP_HTTP_PORT. Example: `stdio` |

### What can MongoDB MCP Server read and change?

**It can read**

- Databases, collections, documents, indexes and logs on the deployment you connect to
- Atlas organisations, projects, clusters, users, alerts and Performance Advisor data, with Atlas credentials
- MongoDB's documentation, through the Assistant tools

**It can change**

- Documents, collections, indexes and whole databases, unless --readOnly is on
- Atlas clusters, database users and the IP access list, with Atlas credentials
- Local Docker containers, through the Atlas Local tools

**Safer setup:** Start with --readOnly and a database user that only has read access. If you turn writes on, keep the default confirmation prompts, and use MDB_MCP_DISABLED_TOOLS to drop anything you never want, such as delete.

### Good for

- Asking questions of a real collection without writing the aggregation pipeline yourself
- Finding slow queries and missing indexes with explain and the Performance Advisor
- Spinning up a free Atlas cluster or a local Atlas deployment for a prototype

### MongoDB MCP Server not working? Common fixes

**The server will not start or complains about the Node.js version**
It needs Node.js 22.13 or newer (20.19 still runs but is deprecated). Check with node -v and upgrade.

**The Atlas tools are missing**
They only load when MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET are set. A connection string alone gives the database tools.

**insert-many, update-many or the drop tools do not appear**
That is read-only mode working. Remove --readOnly from args, or set MDB_MCP_READ_ONLY to false, once you want changes.

**Connecting to an Atlas cluster times out**
Add your IP to the cluster's access list, or let the assistant do it with atlas-create-access-list. Behind a company proxy, set HTTPS_PROXY as the README describes.

**Queries come back cut short**
find and aggregate return 100 documents at most by default. Ask for a smaller projection, or raise MDB_MCP_MAX_DOCUMENTS_PER_QUERY.

### What are the alternatives to MongoDB MCP Server?

| Server | What it does | Tools | Runs on | Licence | Stars |
| --- | --- | --- | --- | --- | --- |
| [MongoDB MCP Server](https://mcpshelf.co/servers/mongodb) | Query, inspect and manage MongoDB databases and Atlas clusters, read-only if you like. | 20 | Your computer | Apache-2.0 | 1.2K |
| [ClickHouse MCP Server](https://mcpshelf.co/servers/clickhouse) | ClickHouse's own server: read-only SQL on your cluster, plus chDB for local files. | 3 | Your computer | Apache-2.0 | 898 |
| [Neon MCP Server](https://mcpshelf.co/servers/neon) | Neon Postgres from chat: projects, branches, SQL and migrations tested on a branch. | 65 | Hosted | MIT | 658 |
| [Redis MCP Server](https://mcpshelf.co/servers/redis) | Redis's own server: keys, hashes, streams, JSON and vector search in plain English. | 53 | Your computer | MIT | 641 |
| [Postgres MCP Pro](https://mcpshelf.co/servers/postgres-mcp-pro) | SQL, query plans, health checks and index advice for Postgres. | 9 | Your computer | MIT | 3.4K |
| [Supabase](https://mcpshelf.co/servers/supabase) | Manage Supabase projects, tables, migrations, logs and Edge Functions. | 29 | Hosted | Apache-2.0 | 3K |

### MongoDB MCP Server FAQ

#### Is the MongoDB MCP Server official?

Yes. MongoDB builds it in the mongodb-js organisation on GitHub, publishes it on npm as mongodb-mcp-server and documents it on mongodb.com. It is Apache-2.0 licensed.

#### How do I install the MongoDB MCP Server in Claude Code?

Run npx -y mongodb-mcp-server@latest setup and follow the prompts, or install MongoDB's plugin from the Claude plugin directory. By hand: claude mcp add mongodb -e MDB_MCP_CONNECTION_STRING=your-string -- npx -y mongodb-mcp-server@latest --readOnly.

#### Can the assistant delete my data?

Not with --readOnly, which only loads read, connect and metadata tools. With writes on it can update and delete; drops and delete-many ask you first by default, but only in clients that support MCP confirmation prompts (elicitation). A read-only database user is the strongest guard.

#### Does it work with MongoDB Atlas and with a local MongoDB?

Both. Any connection string works, Atlas or self-managed. Atlas service account credentials add tools for clusters, users and access lists, and the Atlas Local tools manage a Docker deployment on your machine.

#### Is there a hosted MongoDB MCP server?

Yes, for Atlas. MongoDB runs a remote server that signs in with OAuth; the mongodb-atlas plugin connects to it, and a client without OAuth can use the mongodb-atlas-mcp-remote package with an Atlas MCP configuration's client ID and secret.

#### Why put the connection string in env rather than args?

Arguments show up in process lists and logs on your machine. The README recommends environment variables for connection strings and Atlas secrets for that reason.

#### Does the MongoDB MCP Server send telemetry?

Yes, anonymous usage telemetry by default. Set MDB_MCP_TELEMETRY to disabled, or pass --telemetry disabled, to turn it off.

#### What does it cost?

The server is free and open source. You pay only for whatever MongoDB deployment you connect it to, and Atlas has a free cluster tier the server can create for you.

#### How do I add MongoDB MCP Server to Cursor?

In ~/.cursor/mcp.json, or .cursor/mcp.json for one project, add an entry named mongodb that runs npx -y mongodb-mcp-server@latest --readOnly, with MDB_MCP_CONNECTION_STRING set under env. Save, and the tools show up in Agent chat. Cursor's marketplace has both MongoDB plugins, mongodb and mongodb-atlas, which set this up for you.

#### Can I use MongoDB MCP Server in VS Code?

Yes, through GitHub Copilot. In .vscode/mcp.json, add a server named mongodb with type stdio that runs npx -y mongodb-mcp-server@latest --readOnly, with MDB_MCP_CONNECTION_STRING set under env. Then switch Copilot Chat to Agent mode to use its tools.

#### Does MongoDB MCP Server work with Codex?

Yes. Run codex mcp add mongodb --env MDB_MCP_CONNECTION_STRING=mongodb://localhost:27017/myDatabase -- npx -y mongodb-mcp-server@latest --readOnly in a terminal, or add an [mcp_servers.mongodb] table to ~/.codex/config.toml, which the Codex CLI and IDE extension share.

Full docs on GitHub: https://github.com/mongodb-js/mongodb-mcp-server

## Notes for agents

Fetch these instead of parsing the HTML page:

- llms.txt: https://mcpshelf.co/llms.txt
- llms-full.txt: https://mcpshelf.co/llms-full.txt
- ai.txt: https://mcpshelf.co/ai.txt
- Full catalog (.md): https://mcpshelf.co/catalog.md
- API spec: https://mcpshelf.co/openapi.json
- MCP server: https://mcpshelf.co/mcp
- MCP manifest: https://mcpshelf.co/.well-known/mcp.json
- Developer docs: https://mcpshelf.co/developers

MCP endpoint (Streamable HTTP, no key): https://mcpshelf.co/mcp. REST API: https://mcpshelf.co/api/v1.

