MongoDB集成服务器

MongoDB MCP服务器

也有俄语版本： README-ru.md

备注这个项目是为我的个人需求而设计的。我不打算用我不使用或无法验证的功能来扩展它的功能。您可以自由提交建议和拉取请求，但我不保证所有内容都会被接受。

MCP服务器，用于全面集成MongoDB，具有以下功能：

• 数据库操作 -连接到MongoDB实例，列出数据库和集合
• 文档管理 -查找、聚合和计数文档
• 模式分析 -分析集合模式和索引
• 查询工具 -使用完整的MongoDB语法执行查询和聚合
• 连接管理 -使用只读模式支持管理MongoDB连接
• 流文件导出 -流式保存到大型数据集的文件
• 只读模式 -安全的只读操作，防止意外的数据修改
• 监控 -数据库统计、性能指标和MongoDB日志
• 查询分析 -性能优化的执行计划分析

目录

• 目录
• 需求
• Qwen码配置
• VS代码库配置
• MCP工具
  • 只读模式工具
  • 非只读模式工具
• 安全注意事项
• 并发注意事项
• 本地开发

需求

• Node.js≥22（节点20在2026-04-30达到EOL）
• 环境变量：
  • MONGODB_MCP_CONNECTION_STRING --MongoDB连接字符串（MongoDB://或MongoDB+srv://格式）
  • MONGODB_MCP_DEFAULT_DATABASE --操作的可选默认数据库名称
  • MONGODB_MCP_TIMEZONE --日期操作的可选时区（默认： Europe/Moscow)，必须是有效的IANA时区标识符（例如。， Europe/London, America/New_York, Asia/Tokyo)

Qwen码配置

使用此MCP服务器 Qwen代码，添加到 ~/.qwen/settings.json:

{
  "mcpServers": {
    "mongodb-mcp": {
      "command": "npx",
      "args": ["-y", "@vitalyostanin/mongodb-mcp@latest"],
      "env": {
        "MONGODB_MCP_CONNECTION_STRING": "mongodb://localhost:27017"
      }
    }
  }
}

注： 此配置使用npx运行已发布的包。对于当地发展，使用 "command": "node" 随着 "args": ["/absolute/path/to/mongodb-mcp/dist/index.js"]The MONGODB_MCP_TIMEZONE 环境变量是可选的。

VS代码库配置

使用此MCP服务器 克莱恩 VS代码中的扩展名：

1. 打开安装了Cline扩展的VS代码
2. 单击Cline顶部导航中的MCP服务器图标
3. 选择“配置”选项卡，然后单击“配置MCP服务器”
4. 将以下配置添加到 cline_mcp_settings.json:

{
  "mcpServers": {
    "mongodb-mcp": {
      "command": "npx",
      "args": ["-y", "@vitalyostanin/mongodb-mcp@latest"],
      "env": {
        "MONGODB_MCP_CONNECTION_STRING": "mongodb://localhost:27017"
      }
    }
  }
}

注： 此配置使用npx运行已发布的包。对于当地发展，使用 "command": "node" 随着 "args": ["/absolute/path/to/mongodb-mcp/dist/index.js"]The MONGODB_MCP_TIMEZONE 环境变量是可选的。

MCP工具

只读模式工具

非只读模式工具

注： 默认情况下，服务器以只读模式运行，以防止意外的数据修改。在只读模式下，所有写入操作都会被阻止，包括：

• 数据库级操作： insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, createIndex, dropIndex, dropDatabase, renameCollection等等。
• 收集级别操作： insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, findOneAndReplace, findOneAndUpdate, findOneAndDelete, bulkWrite, createIndex, dropIndex, drop等等。
• 修改数据的聚合阶段： $out, $merge

以下聚合阶段在只读模式下受到限制： $out, $merge。这些阶段仅在服务器以读写模式运行时可用。

安全注意事项

MCP服务器安全生产使用建议：

• 对远程MongoDB集群使用TLS。 更喜欢 mongodb+srv:// （TLS是隐含的）或设置 tls=true 明确地在规则中 mongodb:// 连接字符串。明文连接向网络路径上的任何人公开凭据和查询有效负载。
• 应用最低权限角色。 创建一个专用的MongoDB用户，仅对所需的数据库具有只读访问权限。避免 root, dbAdmin，或授予的任何角色 eval /脚本权限。除非需要写入工具，否则默认为只读模式。
• 将连接字符串排除在MCP主机参数之外。 配置 MONGODB_MCP_CONNECTION_STRING 通过环境变量（例如。， .env 文件）而不是传递它 args MCP主机配置-- args 通常在主机启动服务器时记录，泄露密码。
• 禁用服务器端JavaScript。 MCP服务器已阻止 $where, $function，以及 $accumulator 查询中的运算符。为了进行深度防御，请运行MongoDB服务器本身 --javascriptEnabled=false （或同等产品 security.javascriptEnabled: false 在 mongod.conf).
• 限制导出目录。 使用文件导出工具时，设置 MONGODB_MCP_EXPORT_DIR 指向仅MCP用户可访问的目录(chmod 700).机器上的其他用户不应该能够读取写入工具生成的转储。

并发注意事项

MCP服务器不提供超出MongoDB本身强制范围的事务或排序保证。相应地规划多步骤交互：

• 工具是独立的操作。 每个调用都在自己的隐式上下文中运行；服务器不启动多语句事务或共享 ClientSession 跨电话。通过将先决条件编码到 filter 相同的 update / delete 调用，而不是链接一个单独的 find 接着是一个变异的呼叫。
• Singleton客户端，并行操作。 一个 MongoClient 在所有工具调用中共享。仅 connect / disconnect 通过内部互斥体进行序列化；常规操作(find, aggregate, insert等等）对集群并发执行，MCP服务器不强制执行跨工具排序。
• 连接状态是一个快照。 getConnectionInfo() 返回调用时的状态。对于依赖于连接性的决策，请依赖下一次操作的结果，而不是前一次操作 isConnected 检查一下——两者之间的连接可能会断开。
• 文件导出用途 wx. 写入文件的工具使用以下命令打开目标 wx 标记，并且不会覆盖现有文件。针对同一目标的并发呼叫 filePath 将失败 EEXIST；呼叫者必须选择新的路径（例如，包含时间戳或每次呼叫后缀）。

本地开发

使用源代码的快速参考。

先决条件：

• Node.js如中所述 .nvmrc （当前LTS≥22）。使用nvm： nvm use.
• npm。

设置：

git clone https://github.com/VitalyOstanin/mongodb-mcp.git
cd mongodb-mcp
npm install

常用脚本：

本地连接示例：

export MONGODB_MCP_CONNECTION_STRING="mongodb://localhost:27017"
npm run dev

布局：

• index.ts --CLI入口点。
• src/server.ts --MCP服务器引导。
• src/mongodb-client.ts --具有只读代理的单例MongoDB客户端。
• src/tools/ --每个文件一个MCP工具及其 *.test.ts.
• src/utils/ --共享助手（流式导出、模式片段、日期处理、编校）。