MongoDB MCP Server

MongoDB MCP Server

一个 Model Context Protocol（MCP）服务，可让 Claude 与 MongoDB 数据库交互。此实现让 Claude 能够执行各种 MongoDB 操作，包括查询、聚合、数据操作（CRUD）和数据库管理，且均可直接在对话中完成。

概览

此 MongoDB MCP 服务实现了 Model Context Protocol，在 Claude 与 MongoDB 数据库之间搭建桥梁。它让 Claude 能够通过标准化接口执行 MongoDB 命令，从而直接在对话中分析、管理和处理数据。

功能

• 全面的 MongoDB 操作：查询文档（find、findOne）、执行聚合（aggregate）、统计文档数量（count）、获取不同的值（distinct）以及抽样数据（sample）。
• 数据操作：插入（insertOne、insertMany）、更新（updateOne、updateMany）和删除（deleteOne、deleteMany）文档。
• 数据库管理：列出数据库（listDatabases）、列出集合（listCollections）和删除集合（dropCollection）。
• 查询分析：获取聚合管道的执行计划（explain）。
• 灵活选择数据库：为每项操作指定目标数据库（默认使用 DEFAULT_DATABASE）。
• 安全连接：使用环境变量中的凭据连接 MongoDB。
• 轻松集成：可通过 MCP 系统与 Claude Desktop 或 Cursor 配合使用。

安装

先决条件

• Node.js（建议使用 v14 或更高版本）
• 可访问 MongoDB 实例（本地或 Atlas）
• Claude Desktop 或 Cursor 应用程序

设置

1. 克隆此仓库（如果是从他人仓库派生的，请将 ryaker 替换为你的用户名）：

   git clone [email protected]:ryaker/mongodb-mcp-server.git
   # 或者按需使用 HTTPS
   # git clone https://github.com/ryaker/mongodb-mcp-server.git
   cd mongodb-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 配置 Claude Desktop 或 Cursor：

   • 找到 MCP 配置设置。在 Cursor 中，通常位于 Settings > Extensions > Model Context Protocol。在 Claude Desktop 中，配置可能位于 config.json 文件中。
   • 为此服务添加一个条目，确保提供 mongo-mcp-server.js 文件的正确绝对路径，并设置所需的环境变量。

   配置示例（根据需要调整路径）：

   {
     "mcpServers": {
       "mongo-custom-server": { // 你可以为此键指定任意描述性名称
         "command": "node",
         "args": ["/Volumes/Dev/localDev/MCPServers/CustomMongo_clean/mongo-mcp-server.js"], // <-- 请确保此路径正确！
         "env": {
           "MONGODB_URI": "mongodb+srv://your_username:your_password@your_cluster.mongodb.net/?retryWrites=true&w=majority", // <-- 你的 MongoDB 连接字符串
           "DEFAULT_DATABASE": "YourDefaultDbName" // <-- 可选：设置默认数据库
         }
       }
     }
   }
   

   • 重要： 将占位符 MONGODB_URI 替换为实际的 MongoDB 连接字符串。确保 URI 中指定的用户拥有执行你计划进行的操作所需的权限。
   • DEFAULT_DATABASE 为可选项。如果设置了此项，除非工具调用中的 database 参数另行指定，否则操作将针对该数据库执行。

4. 重启 Claude Desktop 或 Cursor，以加载新的 MCP 服务。

工具参考

此服务提供以下工具。大多数工具都接受可选的 database 参数来指定目标数据库；否则会使用环境变量中设置的 DEFAULT_DATABASE。

查询与读取

1. aggregate：运行 MongoDB 聚合管道。
   • collection（string，必填）：集合名称。
   • pipeline（array，必填）：聚合管道阶段。
   • database（string，可选）：目标数据库。
2. sample：获取随机抽样文档。
   • collection（string，必填）：集合名称。
   • count（number，可选，默认值：5，最大值：10）：要抽样的文档数量。
   • database（string，可选）：目标数据库。
3. explain：获取聚合管道的执行计划。
   • collection（string，必填）：集合名称。
   • pipeline（array，必填）：聚合管道阶段。
   • database（string，可选）：目标数据库。
4. find：查找符合查询条件的文档。
   • collection（string，必填）：集合名称。
   • filter（object，可选，默认值：{}）：查询筛选条件。
   • projection（object，可选，默认值：{}）：要包含或排除的字段。
   • limit（number，可选，默认值：10，最大值：100）：要返回的文档数量上限。
   • sort（object，可选，默认值：{}）：排序条件。
   • database（string，可选）：目标数据库。
5. findOne：查找符合查询条件的单个文档。
   • collection（string，必填）：集合名称。
   • filter（object，必填）：查询筛选条件。
   • projection（object，可选，默认值：{}）：要包含或排除的字段。
   • database（string，可选）：目标数据库。
6. count：统计符合查询条件的文档数量。
   • collection（string，必填）：集合名称。
   • filter（object，可选，默认值：{}）：查询筛选条件。
   • database（string，可选）：目标数据库。
7. distinct：获取某个字段的不同值。
   • collection（string，必填）：集合名称。
   • field（string，必填）：字段名称。
   • filter（object，可选，默认值：{}）：查询筛选条件。
   • database（string，可选）：目标数据库。

数据操作（写入/删除）

8. insertOne：插入单个文档。
   • collection（string，必填）：集合名称。
   • document（object，必填）：要插入的文档。
   • database（string，可选）：目标数据库。
9. insertMany：插入多个文档。
   • collection（string，必填）：集合名称。
   • documents（array，必填）：文档数组。
   • database（string，可选）：目标数据库。
10. updateOne：更新单个文档。
    • collection（string，必填）：集合名称。
    • filter（object，必填）：用于选择文档的筛选条件。
    • update（object，必填）：更新操作（例如，$set）。
    • upsert（boolean，可选，默认值：false）：未找到时是否创建？
    • database（string，可选）：目标数据库。
11. updateMany：更新多个文档。
    • collection（string，必填）：集合名称。
    • filter（object，必填）：用于选择文档的筛选条件。
    • update（object，必填）：更新操作。
    • database（string，可选）：目标数据库。
12. deleteOne：删除单个文档。
    • collection（string，必填）：集合名称。
    • filter（object，必填）：用于选择文档的筛选条件。
    • database（string，可选）：目标数据库。
13. deleteMany：删除多个文档。
    • collection（string，必填）：集合名称。
    • filter（object，必填）：用于选择文档的筛选条件。
    • database（string，可选）：目标数据库。

数据库/集合管理 14. listCollections：列出数据库中的所有集合。 * nameOnly（boolean，可选，默认值：false）：是否仅返回名称？ * database（string，可选）：目标数据库。 15. listDatabases：列出服务器上的所有数据库。 * nameOnly（boolean，可选，默认值：true）：是否仅返回名称？ 16. dropCollection：删除整个集合。 * collection（string，必填）：要删除的集合名称。 * confirm（boolean，必填）：必须为 true 才能确认删除。 * database（string，可选）：目标数据库。

使用示例

查询数据：

User: Find the 5 most recent user documents in the 'users' collection.
Claude: (Calls 'find' with collection='users', limit=5, sort={createdAt: -1})

User: Show me the user document with email '[email protected]'.
Claude: (Calls 'findOne' with collection='users', filter={email: '[email protected]'})

User: How many orders were placed yesterday in the 'orders' collection in the 'sales' database?
Claude: (Calls 'count' with collection='orders', filter={orderDate: {$gte: startOfDay, $lt: endOfDay}}, database='sales')

聚合数据：

User: What are the distinct product categories in the 'products' collection?
Claude: (Calls 'distinct' with collection='products', field='category')

User: Show me the total sales per month from the 'orders' collection.
Claude: (Calls 'aggregate' with collection='orders', pipeline=[...])

修改数据：

User: Insert a new user document: { name: 'Alice', email: '[email protected]' }
Claude: (Calls 'insertOne' with collection='users', document={ name: 'Alice', email: '[email protected]' })

User: Update the user with email '[email protected]' to set their status to 'active'.
Claude: (Calls 'updateOne' with collection='users', filter={email: '[email protected]'}, update={$set: {status: 'active'}})

User: Delete all log entries older than 30 days from the 'logs' collection.
Claude: (Calls 'deleteMany' with collection='logs', filter={timestamp: {$lt: thirtyDaysAgo}})

管理集合：

User: List all collections in the 'staging' database.
Claude: (Calls 'listCollections' with database='staging')

User: Please drop the 'test_data' collection. Confirm deletion.
Claude: (Calls 'dropCollection' with collection='test_data', confirm=true)

安全注意事项

• 切勿将数据库凭据硬编码在服务文件中，或将其提交到版本控制系统。
• 始终使用环境变量（MONGODB_URI）存储连接字符串。
• 为此 MCP 服务创建专用的 MongoDB 用户，并遵循最小权限原则。仅授予执行预期操作所需的权限。
• 可考虑在 MongoDB Atlas 中使用 IP 访问列表（白名单）来增强安全性。

故障排除

• 连接问题：确认 MONGODB_URI 正确无误。确保 MongoDB 用户拥有所需权限和网络访问权限（防火墙、IP 列表）。通过 Claude Desktop/Cursor 日志检查服务日志（console.error）。
• 找不到工具或工具无法使用：确保服务正在运行，并已在 Claude Desktop/Cursor 中正确配置。检查 MCP 服务路径是否正确。重启 Claude/Cursor。
• 权限错误：检查 MongoDB 用户的角色和权限。

许可证

MIT 许可证

致谢

• Model Context Protocol
• MongoDB Node.js Driver