MongoDB MCP for Claude Code: Read-Only Setup (2026)

Last Verified: October 2026 — commands checked against MongoDB’s official MCP server README

You ask Claude Code why the orders page is slow, and it guesses. It can’t see your documents, your indexes, or the query plan, so you paste sample JSON into the chat and hope it is representative.

The MongoDB MCP server is MongoDB’s official server. It lets Claude Code list your databases, infer a collection’s schema, run find and aggregations, and read explain plans on any MongoDB, local or Atlas. Setup is one command, and one flag keeps it read-only.

On Postgres instead? See Neon MCP or Supabase MCP.

How it works

Youask in plain English

Claude Codepicks the right tool

MongoDB MCPLocal (npx) · sign-in: Connection string

Real data backFind, aggregate, schema, and explain plans on local or Atlas, read-only by flag

Quick Start

Swap in your connection string and run:

claude mcp add --scope user mongodb --env MDB_MCP_CONNECTION_STRING="mongodb+srv://USER:PASS@cluster0.example.mongodb.net/" -- npx -y mongodb-mcp-server@latest --readOnly

Start Claude Code and run /mcp to confirm mongodb is connected. Total time: about 2 minutes. Needs Node.js 22.13 or newer.

⚡ Copy This Prompt: Let Claude Code Install and Verify It For You

Skip the manual steps below and hand the whole job to the agent instead:

You have shell access and the `claude mcp` CLI on my machine. Connect the official MongoDB MCP server to Claude Code and report back. Do not tell me it's done unless step 5 actually confirms it.

1. Run `node -v`. If it is below v22.13.0, stop and tell me to upgrade Node first.
2. Run `claude mcp list`. If a mongodb entry already exists, show it and stop instead of adding a second one.
3. Ask me for my connection string. Never echo the password back in your replies.
4. Run, with my string in place of the placeholder: `claude mcp add --scope user mongodb --env MDB_MCP_CONNECTION_STRING="mongodb+srv://USER:PASS@cluster0.example.mongodb.net/" -- npx -y mongodb-mcp-server@latest --readOnly`
5. Using only read tools, list my databases and the collections in the first one. Do not insert, update, or drop anything.

Step 1 catches the most common failure before anything is installed.

On this page (8 sections)

What You’ll Need
Step-by-Step Setup
Which Setup Should You Use?
What It Can Do
Verify It’s Actually Working
Common Mistakes to Avoid
Q&A
Official Resources

What You’ll Need

Requirement	Why You Need It	Time
Claude Code installed	The client that calls the MongoDB tools	0 min
Node.js 22.13 or newer	The server runs locally through `npx`; Node 20 is deprecated	0–5 min
A MongoDB connection string	Local or Atlas; copy it from Compass or Atlas → Connect	1 min

Step-by-Step Setup

Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.

Step 1 — Check Node

~5 sec

The server refuses to start on old Node, and the error looks like a connection problem. Check first:

node -v

Anything from v22.13.0 up is fine. While you’re here, download the package once so Claude Code doesn’t have to (see the timeout trap below):

npx -y mongodb-mcp-server@latest --version

Step 2 — Create a read-only database user (Atlas)

~1 min

In Atlas, open Database Access and add a user with the built-in Read any database role. Copy the connection string from Connect → Drivers and put that user in it. Even if someone drops --readOnly later, this user still can’t write.

Step 3 — Add the server

~10 sec

The string goes in --env, not as a command-line argument. MongoDB recommends this because arguments show up in process lists and logs. --scope user keeps the password out of the project’s .mcp.json, so it never lands in git:

claude mcp add --scope user mongodb --env MDB_MCP_CONNECTION_STRING="mongodb+srv://USER:PASS@cluster0.example.mongodb.net/" -- npx -y mongodb-mcp-server@latest --readOnly

Everything after -- is the server command. --readOnly registers only read, connect, and metadata tools. When we ran version 3.0.5 with it, the server exposed 20 tools, among them find, aggregate, collection-schema, and explain, and not one insert, update, or drop tool.

Terminal: claude mcp add --scope user mongodb --env MDB_MCP_CONNECTION_STRING="mongodb+srv://USER:PASS@cluster0.example.mongodb.net/" -- npx -y mongodb-mcp-server@latest --readOnly; then MCP_TIMEOUT=60000 claude mcp list — Real run, October 2026. Our first `claude mcp list` timed out after 30 seconds while `npx` downloaded the package; with `MCP_TIMEOUT=60000` it showed *Connected*. That means the server started; it only opens the database connection when a tool runs.

Step 4 — Harden it (optional)

~10 sec

Two more flags worth knowing. --indexCheck rejects any query that would scan a whole collection, which protects big production-sized datasets. Telemetry is on by default; MDB_MCP_TELEMETRY=disabled turns it off:

claude mcp add --scope user mongodb --env MDB_MCP_CONNECTION_STRING="mongodb+srv://..." --env MDB_MCP_TELEMETRY=disabled -- npx -y mongodb-mcp-server@latest --readOnly --indexCheck

Remove the old entry first with claude mcp remove mongodb --scope user.

Robot reading a book beside a database stack, arrows only flowing out of the stack — In read-only mode, Claude Code can read every collection and explain every query, but the write tools never load.

Which Setup Should You Use?

Setup	What Claude Can Do	Use It When
String + `--readOnly`	Query, aggregate, inspect schema and indexes, explain plans	Default for most people
String, no flag	Also insert, update, create indexes, drop collections	Local or throwaway dev data only
Atlas service account (client ID + secret)	Also list clusters, alerts, Performance Advisor, create free clusters	You manage Atlas projects, not just data
Official `mongodb-atlas` plugin	Hosted Atlas MCP server, OAuth sign-in, nothing runs locally	Atlas only, and you’d rather not handle credentials

What It Can Do

Job	Example Ask	Works Read-Only?
Learn a messy collection	“Infer the schema of events and flag fields with mixed types”	Yes
Fix a slow query	“Explain this find on orders and tell me which index it’s missing”	Yes
Answer a data question	“Aggregate last week’s orders by country, top 10”	Yes
Audit indexes	“List indexes on users and the storage size of the collection”	Yes
Build an index	“Create an index on orders by userId and createdAt”	No

Results are capped by default at 100 documents and 16 MB per query (maxDocumentsPerQuery, maxBytesPerQuery), so a careless “show me everything” can’t flood your context. Even with write access, the server asks for confirmation before drop-database, drop-collection, delete-many, and drop-index, and before any aggregation with a $out or $merge stage.

Verify It’s Actually Working

claude mcp list

✔ mongodb    npx -y mongodb-mcp-server@latest –readOnly – Connected
✘ mongodb    Failed to connect → first run timed out downloading; run the --version command from Step 1, then restart
✘ mongodb    Still failing → run node -v (needs 22.13+) and check the string
✘ mongodb    Connected, but every query times out → add your IP in Atlas Network Access

Then ask something only your database knows:

List my MongoDB databases and the collections in the first one, with document counts.

If the names match what you see in Compass or Atlas, it’s working.

Common Mistakes to Avoid

Letting the first run time out. Claude Code gives a server 30 seconds to start, and the first npx download can take longer. In our test that showed up as “Failed to connect,” and the half-finished download then crashed every start with ERR_MODULE_NOT_FOUND. Fix: delete the npx cache folder named in the error, then run npx -y mongodb-mcp-server@latest --version once before starting Claude Code.
Running it on Node 20. Support is deprecated; the minimum is 22.13. Upgrade Node before debugging anything else.
Pasting the connection string as an argument. It ends up in process lists and shell history. Pass it with --env MDB_MCP_CONNECTION_STRING=….
Committing the password. A --scope project entry writes the string into .mcp.json. Use --scope user for anything with credentials.
Trusting the flag alone. --readOnly is one line someone can delete. A database user with only the read role is the lock that holds.
Forgetting Network Access. Atlas blocks unknown IPs. The server connects, then every query hangs. Add your current IP, or the Atlas tools can do it for you with a service account.
Removing --readOnly without a guard. Write mode includes dropping collections. Keep manual approval on; a Claude Code hook can block drop tools outright.

Q&A

Does it work with a local MongoDB, not just Atlas?

Yes. Any connection string works: mongodb://localhost:27017, a Docker container, a self-hosted replica set, or Atlas. The atlas-* tools are the only part that needs Atlas.

What does npx -y mongodb-mcp-server@latest setup do?

It is MongoDB’s interactive installer. It asks for a connection string or Atlas credentials and writes the client config for you. The one-line claude mcp add above does the same for Claude Code.

Can I turn off just some tools instead of all writes?

Yes. --disabledTools (or MDB_MCP_DISABLED_TOOLS) takes tool names, categories (atlas, mongodb), or operation types such as delete. delete,atlas keeps inserts and updates but hides deletes and every Atlas admin tool.

Is there a version without a local server?

For Atlas, yes. MongoDB’s official mongodb-atlas plugin connects Claude to a hosted Atlas MCP server with an OAuth sign-in, so no Node and no connection string on your machine.

Official Resources

mongodb-js/mongodb-mcp-server on GitHub — tool list, every config option, Atlas permissions
MongoDB MCP Server docs — per-client setup, including the hosted Atlas server
Claude Code MCP docs — claude mcp add, --env, and scopes

If this saved you a setup headache, follow @quickpromptco on X for the next MCP guide.