/ 目录 / 演练场 / MongoDB
● 官方 mongodb-js 🔑 需要你的密钥

MongoDB

作者 mongodb-js · mongodb-js/mongodb-mcp-server

让 Claude 查询、聚合和管理 MongoDB Atlas 或自托管集群 — 默认只读,可根据需要按工具放宽权限。

MongoDB 官方 MCP 涵盖驱动程序(任何集群上的 CRUD + 聚合)和 Atlas 控制平面(列出项目、集群、用户)。默认以只读模式运行;需要写入时可为每个命令族显式启用。

为什么要用

核心特性

实时演示

实际使用效果

mongodb.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mongodb",
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mongodb": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mongodb-mcp-server"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

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

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: MongoDB

用 Mongo 聚合管道回答业务问题

👤 使用 Mongo 的产品的 PM 和分析师 ⏱ ~15 min beginner

何时使用: 你需要计数、漏斗或 top-N 列表,不想学习 $group/$lookup 语法。

前置条件
  • 只读连接字符串 — Atlas:创建拥有 readAnyDatabase 权限的数据库用户。自托管:在相关数据库上拥有 read 角色的用户。
步骤
  1. 发现集合
    列出数据库,然后为 app_prod 列出所有集合及其大约的文档数。✓ 已复制
    → 集合目录
  2. 采样并推断 Schema
    usersorders 采样 20 个文档。描述你看到的字段和类型。✓ 已复制
    → 每个集合的 schema 描述
  3. 运行实际的聚合
    过去 30 天内每个国家下了多少订单?按降序排序并限制为 20。✓ 已复制
    → 包含所用管道的结果表

结果: 业务答案,保留确切的管道以便重新运行。

注意事项
  • 没有索引的聚合可能会扫描大量集合 — 始终先检查 .explain(),确保存在支持索引;否则在管道顶部的索引字段上仅添加 $match
搭配使用: notion

推断并记录混乱集合的实际 schema

👤 新入职工程师接触无文档 Mongo ⏱ ~25 min intermediate

何时使用: 该集合已经'无 schema'3 年,没人知道哪些字段实际存在。

步骤
  1. 广泛采样
    events 采样 500 个文档。对于每个顶级字段,报告出现 %、类型和示例值。✓ 已复制
    → 逐字段的出现/类型矩阵
  2. 找到 schema 漂移
    哪些字段在不同文档中有多种类型?按 (field, type) 分组并计数。✓ 已复制
    → 多态字段列表
  3. 生成 TypeScript 类型或 JSON schema
    为'稳定'字段(出现 ≥95%、单一类型)生成 TypeScript interface。将其余字段标记为可选或未知。✓ 已复制
    → 可用的类型定义

结果: 带有已知特点的文档化 schema — 迁移或验证器的基础。

注意事项
  • 500 个文档可能会错过罕见但重要的变体 — 按时间区间采样(每月一次)以捕捉遗留形状
搭配使用: filesystem

审计你的 Atlas 项目以获得安全性和成本

👤 Atlas 上的 DevOps/平台团队 ⏱ ~20 min intermediate

何时使用: 每季度:检查哪些集群规模过大、哪些有较宽的 IP 白名单、谁拥有访问权限。

前置条件
  • Atlas API 公钥+私钥 — cloud.mongodb.com → Organization Access → API keys;项目范围
步骤
  1. 列出项目 + 集群
    列出每个项目及其内的每个集群及其层级、区域和备份状态。✓ 已复制
    → 完整清单
  2. 标记风险访问
    对于每个项目,转储 IP 访问列表。标记任何 0.0.0.0/0 条目及其项目名称。✓ 已复制
    → 风险访问报告
  3. 建议正确调整大小
    任何使用少于 10GB 的 M30+ 集群?建议降级。✓ 已复制
    → 成本节省列表

结果: 供安全性和财务部门使用的短整改清单。

注意事项
  • API 密钥范围太窄,无法看到每个项目 — 使用组织级密钥以只读模式,而不是项目级密钥
搭配使用: notion

安全地提议和执行一次性数据清理

👤 后端工程师修复数据错误 ⏱ ~30 min advanced

何时使用: 一个错误导致了坏写入;你需要修复大约 10k 个文档,但必须不摧毁错误的文档。

前置条件
  • 可写用户(仅限于目标数据库) — Atlas:只在该数据库上具有 readWrite 角色,没有其他
  • 此会话明确关闭 --read-only — 不使用 --read-only 启动 MCP
步骤
  1. 用计数确定修复范围
    计算 usersstatus='active' AND last_login IS NULL AND created_at < 2024-01-01 的文档。不修改任何内容。✓ 已复制
    → 预期受影响的计数,例如 9,873
  2. 更新的试运行
    显示你将运行的 updateMany 管道(filter + $set),并显示将被更改的 5 个示例文档。不要执行。✓ 已复制
    → Filter + set 预览
  3. 执行并限制和验证
    运行更新。然后重新运行原始计数 — 应该是 0。报告 matchedCount 和 modifiedCount。✓ 已复制
    → 计数符合预期;验证查询返回 0

结果: 一个干净、可审计的修复,包含前后计数。

注意事项
  • 使用坏 filter 的 updateMany 摧毁整个集合 — 始终先将 filter 作为 countDocuments 运行;如果计数出乎意料,停止并调查
  • 受影响的切片无备份 — 在更新之前将匹配的文档复制到 <collection>_backup_<date> 集合
搭配使用: filesystem

从缓慢查询模式建议缺少的索引

👤 寻找性能问题的后端工程师 ⏱ ~25 min advanced

何时使用: 你的应用在 Mongo 查询上很慢;你需要一个有针对性的索引计划,而不是散弹枪。

步骤
  1. 检查现有索引
    对于 ordersusers,列出每个索引及其密钥和磁盘大小。✓ 已复制
    → 索引目录
  2. 分析特定查询
    在此查询上运行 .explain('executionStats') [粘贴]。报告 totalDocsExamined vs nReturned 和获胜的计划阶段。✓ 已复制
    → Explain 输出
  3. 提议最小的新索引
    鉴于该计划,提议恰好一个会将其转换为 IXSCAN 的索引。证明字段顺序。✓ 已复制
    → 具体的 createIndex 命令及理由

结果: 每个缓慢查询一个合理的索引建议 — 不是一堵墙。

注意事项
  • 过度索引会降低写入吞吐量并增加存储 — 仅添加服务 >1 个高流量查询的索引;复合索引应反映 ESR(相等、排序、范围)顺序

组合

与其他 MCP 搭配,撬动十倍杠杆

mongodb + notion

聚合,然后发布可共享报告

计算过去 6 个月每个计划层级的 MAU,并在 'Growth / Monthly' 中创建一个 Notion 页面,其中结果为表。✓ 已复制
mongodb + filesystem

清理前将集合切片备份为 JSONL

找到 users 中匹配 <filter> 的所有文档,保存到 /backups/users-cleanup-<date>.jsonl,然后删除它们。✓ 已复制
mongodb + postgres

迁离 Mongo 时的跨数据库对账

对于 Mongo users 中的每个 user_id,检查 Postgres users 中是否存在相应行。报告不匹配。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
list_databases 任何探索会话的开始 free
list_collections database: str 清点数据库 free
find database, collection, filter?, projection?, sort?, limit? 读取文档 — 主要读取工具 free
aggregate database, collection, pipeline: stage[] 分组、连接、分析 free
count database, collection, filter? 总是在破坏性写入之前 — 确认范围 free
insert_one / insert_many database, collection, document(s) 需要 --read-only 关闭 writes
update_one / update_many database, collection, filter, update 始终先使用计数预览 filter writes
delete_one / delete_many database, collection, filter 危险 — 需要明确的用户确认 writes
list_indexes database, collection 建议新索引前的性能分析 free
atlas_list_projects / atlas_list_clusters Atlas 控制平面审计 free

成本与限制

运行它的成本

API 配额
驱动程序:受集群连接限制限制。Atlas API:每个密钥 100 req/分钟。
每次调用 Token 数
Find/aggregate:随结果大小缩放;使用投影和限制。
费用
针对现有集群免费。Atlas 有一个免费的 M0 层进行测试。
提示
始终仅投影你需要的字段;无界 find 返回消耗上下文和出口的大文档。

安全

权限、密钥、影响范围

最小权限: readAnyDatabase(只读)或在特定数据库上读取
凭据存储: 驱动程序使用 MDB_MCP_CONNECTION_STRING;Atlas 使用 MDB_MCP_API_CLIENT_ID + MDB_MCP_API_CLIENT_SECRET
数据出站: 驱动程序连接到你的集群;Atlas API 仅连接到 cloud.mongodb.com
切勿授予: dbAdminAnyDatabase userAdminAnyDatabase root

故障排查

常见错误与修复

MongoServerError: Authentication failed

连接字符串用户/密码错误或用户缺少认证数据库。为 Atlas 添加 ?authSource=admin

验证: mongosh '$MDB_MCP_CONNECTION_STRING' --eval 'db.runCommand({ping:1})'
MongoNetworkError: ETIMEDOUT

IP 不在 Atlas 白名单中。在 Atlas → Network Access 中添加你的当前 IP。

验证: curl ifconfig.me then compare
not authorized on admin to execute command listDatabases

角色太窄。授予 clusterMonitor 或改为通过 listCollections 将工具范围限制在特定数据库。

Write rejected / running in read-only mode

不使用 --read-only 重启 MCP;仅为特定的修复会话执行此操作。

替代方案

MongoDB 对比其他方案

替代方案何时用它替代权衡
Postgres MCP你在 Postgres 上,或考虑从 Mongo 迁移关系型 — 文档风格的灵活性消失
DBHub你需要一个 MCP 来支持 Mongo + 多个 SQL 数据库Mongo 功能覆盖比官方服务器浅

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills