/ 目錄 / 演練場 / 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. 取樣並推論結構描述
    usersorders 各取樣 20 筆文件,描述看到的欄位與型別。✓ 已複製
    → 各集合的結構描述說明
  3. 執行實際聚合
    過去 30 天內各國下單數量為何?依降冪排列並限制 20 筆。✓ 已複製
    → 附帶所用管道的結果表格

結果: 業務解答,並保留完整管道以便重複執行。

注意事項
  • 未使用索引的聚合可能掃描龐大集合 — 務必先執行 .explain() 確認有對應索引;否則在管道最前面用已索引欄位加上精確的 $match
搭配使用: notion

推論並記錄結構混亂的集合實際結構描述

👤 接手無文件化 Mongo 的新進工程師 ⏱ ~25 min intermediate

何時使用: 該集合「無結構」運作了 3 年,沒人知道實際存在哪些欄位。

步驟
  1. 廣泛取樣
    events 取樣 500 筆文件,針對每個頂層欄位回報出現比例、型別,以及一個範例值。✓ 已複製
    → 欄位級別的出現率與型別矩陣
  2. 找出結構漂移
    哪些欄位在不同文件中有多種型別?依 (欄位, 型別) 分組並計數。✓ 已複製
    → 多型態欄位清單
  3. 產生 TypeScript 型別或 JSON Schema
    為「穩定」欄位(出現率 ≥95%、單一型別)產生 TypeScript interface,其餘標為選填或 unknown。✓ 已複製
    → 可用的型別定義

結果: 有文件記錄的結構描述,附已知的特殊情況——可作為遷移或驗證器的基礎。

注意事項
  • 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. 建議降規
    是否有 M30 以上但使用量不足 10GB 的叢集?建議降規方案。✓ 已複製
    → 節省成本清單

結果: 提供給安全與財務人員的簡短修復清單。

注意事項
  • API 金鑰範圍過窄,無法查看所有專案 — 改用組織層級的唯讀金鑰,而非專案層級的金鑰
搭配使用: notion

安全地提案並執行一次性資料清理

👤 修復資料錯誤的後端工程師 ⏱ ~30 min advanced

何時使用: 某個 bug 造成錯誤寫入;需要修復約 1 萬筆文件,但不能誤刪其他資料。

前置條件
  • 可寫入的使用者(僅限目標資料庫) — Atlas:對該資料庫賦予 readWrite 角色,其他一概不給
  • 此次工作階段明確關閉 --read-only — 啟動 MCP 時不加 --read-only
步驟
  1. 用計數確認修復範圍
    計算 usersstatus='active'last_login IS NULLcreated_at < 2024-01-01 的文件數,不要修改任何資料。✓ 已複製
    → 預計影響數量,例如 9,873
  2. 模擬執行更新
    展示你將執行的 updateMany 管道(篩選條件 + $set),以及 5 筆將被修改的範例文件,不要實際執行。✓ 已複製
    → 篩選條件與更新內容預覽
  3. 執行並驗證
    執行更新,再重新執行原始計數——結果應為 0,回報 matchedCount 與 modifiedCount。✓ 已複製
    → 計數符合預期;驗證查詢返回 0

結果: 乾淨且可稽核的修復,附前後計數紀錄。

注意事項
  • updateMany 若篩選條件有誤,會清空整個集合 — 務必先用 countDocuments 執行篩選條件;若計數出乎意料,立即停止並調查
  • 未備份受影響的資料切片 — 更新前先將符合條件的文件複製到 <collection>_backup_<date> 集合
搭配使用: filesystem

從慢查詢模式建議缺少的索引

👤 追查效能問題的後端工程師 ⏱ ~25 min advanced

何時使用: 應用程式的 Mongo 查詢很慢,想要有針對性的索引計畫,而非散彈槍式的建議。

步驟
  1. 檢查現有索引
    列出 ordersusers 的所有索引及其欄位與磁碟大小。✓ 已複製
    → 索引目錄
  2. 分析特定查詢
    對此查詢 [貼上查詢] 執行 .explain('executionStats'),回報 totalDocsExamined 對比 nReturned,以及最終執行計畫階段。✓ 已複製
    → Explain 輸出結果
  3. 提議最精簡的新索引
    根據該執行計畫,提議恰好一個能將此查詢轉為 IXSCAN 的索引,並說明欄位順序的理由。✓ 已複製
    → 附理由的具體 createIndex 指令

結果: 每條慢查詢一個有根據的索引建議,而非一大堆建議。

注意事項
  • 過度建立索引會降低寫入吞吐量並膨脹儲存空間 — 只新增能服務超過 1 個高流量查詢的索引;複合索引應遵循 ESR(相等、排序、範圍)欄位順序

組合

與其他 MCP 搭配,撬動十倍槓桿

mongodb + notion

聚合資料後發布可分享的報告

計算過去 6 個月各方案層級的 MAU,並在 Notion 的「Growth / Monthly」中建立一個含結果表格的頁面。✓ 已複製
mongodb + filesystem

清理前先將集合切片備份為 JSONL

找出 users 中符合 <篩選條件> 的所有文件,儲存至 /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 執行前務必先用 count 預覽篩選條件 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 次請求。
每次呼叫 Token 數
Find/aggregate:隨結果大小而增加;請使用投影與限制筆數。
費用
對現有叢集免費使用。Atlas 提供免費的 M0 層級供測試。
提示
只投影所需欄位;無限制的查詢會返回大量文件,消耗大量 context 與流量費用。

安全

權限、密鑰、影響範圍

最小權限: readAnyDatabase (read-only) or read on specific DBs
憑證儲存: 驅動層使用 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