MongoDB MCP — Install & Live Demo

Why use it

Key features

Works against MongoDB Atlas, Enterprise, or Community — same tools
CRUD + aggregation pipelines with full query/projection/sort support
Atlas admin surface: projects, clusters, DB users, IP allowlist
Read-only by default; writes opt-in via --read-only flag
Schema inference: infer a collection's shape by sampling

Live Demo

What it looks like in practice

mongodb.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mongodb",
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mongodb": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mongodb-mcp-server"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add mongodb -- npx -y mongodb-mcp-server

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use MongoDB

Answer business questions with Mongo aggregation pipelines

👤 PMs and analysts on a Mongo-backed product ⏱ ~15 min beginner

When to use: You need counts, funnels, or top-N lists and don't want to learn $group/$lookup syntax.

Prerequisites

Read-only connection string — Atlas: create a DB user with readAnyDatabase. Self-hosted: user with read role on relevant DBs.

Flow

Discover collections

List databases, then for app_prod list all collections and their approximate document counts.✓ Copied

→ Collection catalog
Sample and infer schema

Sample 20 docs from users and orders. Describe the fields and types you see.✓ Copied

→ Per-collection schema description
Run the actual aggregation

How many orders were placed per country in the last 30 days? Sort desc and limit 20.✓ Copied

→ Results table with the pipeline used

Outcome: Business answers with the exact pipeline preserved for re-running.

Pitfalls

Aggregations without indexes can scan huge collections — Always check .explain() first and make sure a supporting index exists; otherwise add $match narrowly on an indexed field at the top of the pipeline

Combine with: notion

Infer and document a messy collection's actual schema

👤 New engineer onboarding to an undocumented Mongo ⏱ ~25 min intermediate

When to use: The collection was 'schemaless' for 3 years and nobody knows which fields actually exist.

Flow

Sample broadly

Sample 500 docs from events. For each top-level field, report presence %, type(s), and a sample value.✓ Copied

→ Field-by-field presence/type matrix
Find schema drift

Which fields have multiple types across docs? Group by (field, type) and count.✓ Copied

→ List of polymorphic fields
Produce a TypeScript type or JSON schema

Generate a TypeScript interface for the 'stable' fields (≥95% presence, single type). Mark the rest as optional or unknown.✓ Copied

→ Usable type definition

Outcome: A documented schema with known quirks — the basis for migrations or a validator.

Pitfalls

500 docs may miss rare but important variants — Sample by time bucket (one per month) to catch legacy shapes

Combine with: filesystem

Audit your Atlas projects for security and cost

👤 DevOps/platform teams on Atlas ⏱ ~20 min intermediate

When to use: Quarterly: check which clusters are oversized, which have wide IP allowlists, who has access.

Prerequisites

Atlas API public+private key — cloud.mongodb.com → Organization Access → API keys; project-scoped

Flow

List projects + clusters

List every project and within each, every cluster with its tier, region, and backup status.✓ Copied

→ Full inventory
Flag risky access

For each project, dump the IP access list. Flag any entry of 0.0.0.0/0 with the project name.✓ Copied

→ Risky-access report
Suggest rightsizing

Any cluster on M30+ with fewer than 10GB used? Recommend downgrades.✓ Copied

→ Cost-savings list

Outcome: A short remediation list for your security + finance folks.

Pitfalls

API key scope too narrow to see every project — Use an Organization-level key in read-only mode rather than a project-level one

Combine with: notion

Propose and execute a one-off data cleanup safely

👤 Backend engineer fixing a data bug ⏱ ~30 min advanced

When to use: A bug caused bad writes; you need to fix ~10k docs but must not nuke the wrong ones.

Prerequisites

Writable user (scoped to the target DB only) — Atlas: role with readWrite on that one DB, nothing else
--read-only OFF explicitly for this session — Start the MCP without --read-only

Flow

Scope the fix with a count

Count docs in users where status='active' AND last_login IS NULL AND created_at < 2024-01-01. Don't modify anything.✓ Copied

→ Expected-affected count, e.g. 9,873
Dry-run the update

Show the updateMany pipeline you would run (filter + $set), and show 5 sample docs that would be changed. Do NOT execute.✓ Copied

→ Filter + set preview
Execute with a limit and verify

Run the update. Then re-run the original count — it should be 0. Report matchedCount and modifiedCount.✓ Copied

→ Counts match expectation; verify query returns 0

Outcome: A clean, auditable fix with counts before and after.

Pitfalls

updateMany with a bad filter nukes the whole collection — Always run the filter as countDocuments first; if the count is surprising, stop and investigate
No backup of the affected slice — Copy the matching docs to a <collection>_backup_<date> collection before updating

Combine with: filesystem

Suggest missing indexes from slow-query patterns

👤 Backend engineers hunting perf issues ⏱ ~25 min advanced

When to use: Your app is slow on Mongo queries; you want a targeted index plan, not a shotgun.

Flow

Check existing indexes

For orders and users, list every index with its keys and size on disk.✓ Copied

→ Index catalog
Profile a specific query

Run .explain('executionStats') on this query [paste]. Report totalDocsExamined vs nReturned and the winning plan stage.✓ Copied

→ Explain output
Propose the smallest new index

Given that plan, propose exactly one index that would convert this to IXSCAN. Justify field order.✓ Copied

→ Concrete createIndex command with rationale

Outcome: A single, justifiable index recommendation per slow query — not a wall of them.

Pitfalls

Over-indexing kills write throughput and balloons storage — Only add an index that serves >1 high-traffic query; compound indexes should reflect ESR (Equality, Sort, Range) order

Combinations

Pair with other MCPs for X10 leverage

mongodb + notion

Aggregate, then post a shareable report

Compute MAU per plan tier for the last 6 months and create a Notion page in 'Growth / Monthly' with the results as a table.✓ Copied

mongodb + filesystem

Backup a collection slice as JSONL before a cleanup

Find all docs in users matching <filter>, save to /backups/users-cleanup-<date>.jsonl, then delete them.✓ Copied

mongodb + postgres

Cross-DB reconciliation when migrating off Mongo

For every user_id in Mongo users, check whether a corresponding row exists in Postgres users. Report mismatches.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_databases		Start of any exploration session	free
list_collections	database: str	Inventory a database	free
find	database, collection, filter?, projection?, sort?, limit?	Read documents — the main read workhorse	free
aggregate	database, collection, pipeline: stage[]	Grouping, joining, analytics	free
count	database, collection, filter?	Always before destructive writes — confirm scope	free
insert_one / insert_many	database, collection, document(s)	Requires --read-only off	writes
update_one / update_many	database, collection, filter, update	Always preview filter with count first	writes
delete_one / delete_many	database, collection, filter	Dangerous — require explicit user confirmation	writes
list_indexes	database, collection	Perf analysis before suggesting new indexes	free
atlas_list_projects / atlas_list_clusters		Atlas control-plane audits	free

Cost & Limits

What this costs to run

API quota: Driver: bounded by cluster connection limit. Atlas API: 100 req/min per key.
Tokens per call: Find/aggregate: scales with result size; use projections and limits.
Monetary: Free against your existing cluster. Atlas has a free M0 tier for testing.
Tip: Always project only the fields you need; unbounded finds return large docs that chew context and egress.

Security

Permissions, secrets, blast radius

Minimum scopes: readAnyDatabase (read-only) or read on specific DBs

Credential storage: MDB_MCP_CONNECTION_STRING for driver; MDB_MCP_API_CLIENT_ID + MDB_MCP_API_CLIENT_SECRET for Atlas

Data egress: Driver connects to your cluster; Atlas API to cloud.mongodb.com only

Never grant: dbAdminAnyDatabase userAdminAnyDatabase root

Run with --read-only for exploratory sessions; only disable for explicit fix work.
Never point at prod primary for heavy aggregations; use a hidden/analytics node or Atlas Online Archive.

Troubleshooting

Common errors and fixes

MongoServerError: Authentication failed

Connection string user/password wrong or the user lacks auth DB. Add ?authSource=admin for Atlas.

Verify: mongosh '$MDB_MCP_CONNECTION_STRING' --eval 'db.runCommand({ping:1})'

MongoNetworkError: ETIMEDOUT

IP not in Atlas allowlist. Add your current IP in Atlas → Network Access.

Verify: curl ifconfig.me then compare

not authorized on admin to execute command listDatabases

Role too narrow. Grant clusterMonitor or scope tools to a specific DB via listCollections instead.

Write rejected / running in read-only mode

Restart the MCP without --read-only; only do this for the specific fix session.

Alternatives

MongoDB vs others

Alternative	When to use it instead	Tradeoff
Postgres MCP	You're on Postgres, or considering migrating from Mongo	Relational — document-style flexibility gone
DBHub	You need one MCP for Mongo + several SQL DBs	Shallower Mongo feature coverage than the official server

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills

MongoDB

Why use it

Key features

Live Demo

What it looks like in practice

Install

Pick your client

Use Cases

Real-world ways to use MongoDB

Prerequisites

Flow

Pitfalls

Flow

Pitfalls

Prerequisites

Flow

Pitfalls

Prerequisites

Flow

Pitfalls

Flow

Pitfalls

Combinations

Pair with other MCPs for X10 leverage

Tools

What this MCP exposes

Cost & Limits

What this costs to run

Security

Permissions, secrets, blast radius

Troubleshooting

Common errors and fixes

Alternatives

MongoDB vs others

More

Resources

Related tools and workflows

MongoDB Agent Skills

Milvus MCP

Redis

Couchbase MCP