MCP MongoDB Server

MCP MongoDB 服务

---

一个模型上下文协议（MCP）服务，可让 AI 助手使用你的 MongoDB 数据库。它会公开你的集合、推断其架构，并通过标准接口运行查询、聚合和写入操作，因此 Claude Desktop 和 Cursor 等工具可以读取并分析你的数据。

演示

为什么使用它

• 用日常语言与数据库交互 — 助手会自动发现你的集合及其结构。
• 默认安全 — 开启只读模式后，助手可以探索数据，而不会有更改数据的风险。
• 适用范围广 — 可通过普通连接或 TLS 连接到独立部署、副本集、分片集群和 Atlas 部署。

主要功能

• 只读模式 — 阻止所有写入操作（插入、更新、创建索引，以及可能修改数据的 $out/$merge 等聚合阶段）。
• 智能 ObjectId 处理 — 可配置将 24 位十六进制字符串转换为 ObjectId 的方式：auto/none/force。
• 架构推断 — 根据文档样本自动检测集合架构。
• 查询与聚合 — 完整支持查询和聚合管道，并可选择生成 explain 计划。
• 写入操作 — 插入、更新和创建索引（关闭只读模式时）。
• 时间转换 — convertTime 助手可将 Unix 时间戳和日期字符串转换为 UTC/GMT/ISO 格式，让跨时区的日期查询清晰明确。
• 进度与取消 — 长时间运行的操作会报告进度，并可在执行过程中取消。
• 两种传输方式 — 可通过 stdio 在本地运行，也可公开 HTTP 端点以供远程访问。

要求

• Node.js 20 或更高版本

快速开始

将服务指向你的数据库，无需安装：

npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase

安全地进行探索，不必担心数据会被更改：

npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase --read-only

用法

本地（stdio）

这是默认方式，供 Claude Desktop、Cursor 和其他本地客户端使用：

npx -y mcp-mongo-server "mongodb://user:pass@localhost:27017/mydatabase"

远程（HTTP）

在 /mcp 公开 HTTP 端点，以供远程访问或多个客户端访问：

npx -y mcp-mongo-server "mongodb://user:pass@localhost:27017/mydatabase" --transport http --port 3001

默认情况下，仅接受不带浏览器 Origin 的请求（CLI、IDE）和来自 localhost 的请求；其他请求均会被拒绝，并返回 403，以防范 DNS 重绑定攻击。使用 --allowed-origins 允许特定的浏览器来源：

npx -y mcp-mongo-server "mongodb://..." --transport http --port 3001 --allowed-origins "https://app.example.com"

选项

标志	说明
--read-only, -r	阻止所有写入操作
--allow-cross-db	允许聚合 $out/$merge/$lookup 以其他数据库为目标（默认关闭）
--allow-server-js	允许服务端 JavaScript 运算符 $function/$where/$accumulator（默认关闭）
--transport, -t	stdio（默认）或 http
--port, -p	HTTP 端口（默认 3001）
--allowed-origins	以逗号分隔的浏览器来源列表，在 HTTP 模式下允许这些来源
--json-limit	HTTP 请求正文大小上限（默认 10mb）
--auth-token	要求 HTTP 端点请求携带 Authorization: Bearer <token>

环境变量

变量	说明
MCP_MONGODB_URI	MongoDB 连接 URI（可替代参数）
MCP_MONGODB_READONLY	启用只读模式（"true"）
MCP_MONGODB_ALLOW_CROSS_DB	允许跨数据库聚合阶段（"true"）
MCP_MONGODB_ALLOW_SERVER_JS	允许服务端 JavaScript 运算符（"true"）
MCP_PORT	HTTP 端口
MCP_HTTP_ALLOWED_ORIGINS	以逗号分隔的浏览器来源列表，在 HTTP 模式下允许这些来源
MCP_HTTP_JSON_LIMIT	HTTP 请求正文大小上限（默认 10mb）
MCP_HTTP_AUTH_TOKEN	访问 HTTP 端点所需的 Bearer 令牌

安全

数据库范围。 服务器操作的是连接字符串中指定的数据库。默认情况下，访问其他数据库的聚合阶段（$out、$merge、带有显式 db 的 $lookup）会被拒绝，因此管道无法在你未指定的数据库中偷偷读取或写入数据。如果需要使用这些阶段，请通过 --allow-cross-db 启用。

服务器端 JavaScript。 聚合运算符 $function、$where 和 $accumulator 会在 MongoDB 服务器上运行任意 JavaScript。默认情况下，这些运算符会被拒绝；如果你信任正在运行的管道，请通过 --allow-server-js 启用。

只读模式会阻止所有写入路径，包括会写入数据或运行服务器端 JavaScript 的聚合阶段（$out、$merge、$function、$where、$accumulator）。

最小权限。 应用层检查的作用有限，最有力的保障来自数据库。请使用权限仅限所需数据库的 MongoDB 用户进行连接；如果助手只需进行探索，请赋予其只读权限。这样，数据库本身就能强制执行访问边界，提供纵深防御。

文档

• 集成指南 — Claude Desktop、Windsurf、Cursor、Docker
• 可用工具 — 查询、聚合、更新、插入等
• 开发 — 设置、脚本和调试
• 贡献指南

许可证

MIT — 详情请参阅 LICENSE。