MongoDB MCP for Claude Code: 2026 Guide

MongoDB MCP for Claude Code is the official way to let the Claude Code agent list databases, inspect schemas, run finds, and optionally write, through Model Context Protocol tools instead of pasting shell output. It is the right plug for "what is in the cluster."

It is the wrong plug for "which row did I just highlight in the admin UI." Those are two contexts.

I run both. MongoDB MCP for data. A local screen MCP for the live window. Claude Code stays the client.

If MCP is still abstract, start with what an MCP server is and the Claude Code MCP primer.

What does MongoDB MCP for Claude Code actually expose?

Two official shapes exist in 2026.

Atlas managed (recommended for Atlas). Plugin mongodb-atlas from the Claude marketplace. HTTP plus OAuth. An organization owner must enable AI clients first.

Local / self-managed. Plugin mongodb or npx mongodb-mcp-server@latest. Connection string in env. Node.js 22.12.0 or later. Node 20 reached end of life on 30 Apr 2026. Docker is an alternative if you do not want Node on the Mac.

The local server can run read-only. Turn that on unless the task is a write. I treat write access as a conscious exception.

Tool names you will see in docs and traces include list-databases, create-collection, insert-many, find, collection-schema, count, aggregate, update-many. Treat MongoDB's current doc as the source. Do not freeze a vendor list in your head.

The server is not the model. It runs queries. It does not invent a collection that is not there, unless you gave it write and a sloppy prompt.

How do I install MongoDB MCP for Claude Code?

Atlas path, from a Claude Code session:

/plugin install mongodb-atlas@claude-plugins-official

Then /reload-plugins. Then /mcp, pick the Atlas plugin, Authenticate, finish OAuth, Authorize.

Local path, from a session:

/plugin install mongodb@claude-plugins-official

Then run the bundled setup skill and follow the prompts.

Manual local setup without the plugin:

npx mongodb-mcp-server@latest setup

The utility asks read-only, then a connection string, then a config path. Restart Claude Code. Confirm tools in /mcp.

I keep Atlas at user scope if every repo might query. I keep a local connection string out of git. Project scope is fine if only one service owns the cluster.

A first prompt that is safe: "In read-only mode, explain the schema of products and summarize counts by category. Do not write."

Watch the tool trace. You want collection-schema, find, count, maybe aggregate. If you see insert-many, your read-only flag failed. Stop.

The Claude Code tutorial covers /plugin and /mcp if this is your first session.

Why does a perfect query still ship the wrong UI fix?

The document is correct. The screen that shows it is not. Pagination hid the row. Two tables share a column name.

The agent updates the collection and never touches the renderer. Or it restyles the wrong grid.

Live UI needs Accessibility. AXUIElementCopyElementAtPosition returns role, label, frame, parent chain. Confidence and circled-vs-dwelled provenance tell the agent how the hit happened.

When the overlay would hit-test itself, chainExcludingSelf walks real windows. Electron needs AXManualAccessibility and a short retry. Bare AXGroup should descend to a labeled child.

OCR is the fallback on canvas. Ask below 0.8 confidence.

That bundle is pinvari_next_instruction plus spoken words and a crop. pinvari_request_capture lets the agent ask you to point mid-task.

Atlas plugin

Type: hosted HTTP, OAuth.

Capture: cluster metadata and data your role allows.

Resolution: documents and indexes. No live AX.

Local MCP server

Type: stdio via npx or plugin.

Capture: whatever the connection string can see.

Resolution: same. Read-only if you set it.

Live screen MCP

Type: PinVari connector at ~/.pinvari/mcp/pinvari-mcp on 127.0.0.1:3402.

Capture: crop, transcript, window text up to 40,000 characters.

Resolution: named AX element with confidence.

How do I wire PinVari next to MongoDB MCP for Claude Code?

Install PinVari from the pricing page. The app must be running.

One-click: PinVari → Connect → Claude Code.

CLI, never the bare add without a path:

claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

Hotkey Option-Command-A. Voice-only Option-Command-V. Pause Option-Command-P.

A prompt that works: "Read the products collection for the sku I just spoke. Then take the next PinVari instruction and edit only the named element. If confidence is below 0.8, ask."

Do not paste a connection string into a screen-capture tool. Different secrets, different servers.

pinvari_mark_done closes the UI instruction. Database writes are a separate permission. Do not conflate them.

Bring your own agent. PinVari does not call an LLM. Transcription and OCR stay on-device. MongoDB MCP talks to your cluster. Keep those pipes apart.

Jam.dev still wins for browser console logs. It cannot query Mongo. CleanShot X cannot either.

For a catalog of other connectors, see MCP tools. Keep the set small. A database plus a screen server is enough for most admin-UI days.

How do I debug a dead MongoDB MCP for Claude Code session?

/mcp is the live check. claude mcp list shows config.

Atlas: org AI clients disabled. Ask an owner. OAuth expired. Authenticate again.

Local: Node too old. node --version. Connection string wrong. Run the setup utility again.

Read-only surprise: you asked for an insert and the server refused. That is success. Switch only for a planned write.

Scope surprise: plugin installed in repo A, you opened repo B. Reinstall at user scope or repeat the plugin step.

Duplicate servers: plugin plus a handmade npx block. Remove one.

Canvas-only admin UIs still need OCR. That is not a Mongo bug.

FAQ

Does MongoDB MCP for Claude Code replace Compass?

For agent-driven reads, often. For index design I still open Compass or the Atlas UI. The MCP is a tool, not a DBA.

Should I start with Atlas or local?

Use the Atlas plugin if the data lives on Atlas. Use local for Community or Enterprise on your laptop. Do not point a write-enabled local server at prod.

Can I keep MongoDB at project scope and PinVari at user scope?

Yes. The cluster is a repo concern. The screen connector is a personal Mac tool.

What if the agent writes data I did not ask for?

Turn on read-only. Put a PreToolUse hook on write-shaped MCP tools if you use hooks. Treat that as a process bug, not a one-off.

Is the connection string stored in the repo?

Only if you put it there. Do not. Use env or the setup utility path that stays in your home directory.

Is anything uploaded when I circle a row?

Not by PinVari's default path. MongoDB MCP still talks to your cluster when you ask it to query. Those are separate pipes.

What does a start-to-finish products admin loop look like?

I had a Settings grid that showed inStock as a string. The collection stored a boolean. QA filed "toggle looks wrong."

I opened Claude Code in the API repo. /mcp showed mongodb in read-only and pinvari connected.

Prompt one: "Show the schema and three sample documents for products. Do not write."

The agent called collection-schema and find. The field was boolean. Good.

I reproduced the grid. Option-Command-A on the In stock cell. "This renders as the word true, use a check."

Prompt two: "Take the next PinVari instruction. Edit only the named cell renderer. Do not change the collection."

The agent opened the React cell. It switched a String() wrap to a check icon. Tests were none. I clicked the grid. The check appeared.

I called for pinvari_mark_done. I left Mongo read-only the whole time.

Query first, then mark. If I had marked first, the agent might have flipped documents to strings to match the broken UI.

That loop is why MongoDB MCP for Claude Code exists next to a screen server. Data truth. Pixel address. Two tools.

If the mark had landed on a bare group, confidence would have dropped. I would have marked again instead of letting it guess a class name.

Dwell of about 0.2 seconds works when I do not want to draw. Per-mark word buckets matter if I circle the header and the cell in one breath.

Multi-display: the admin UI was on the laptop, Compass on the studio display. The mark remembered the laptop. The crop matched.

I did not invent Atlas pricing here. Check MongoDB if you need a plan name. PinVari is $39 launch for the capture side.