AI导哈

MongoDB交互服务

一个通过Model Context Protocol (MCP)实现的MongoDB交互服务器，允许Claude执行查询、聚合、数据操作和数据库管理等操作。

  • by ryaker
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 ryaker/mongodb-mcp-server

使用说明

MongoDB MCP服务器

一个模型上下文协议（MCP）服务器，为Claude提供了与MongoDB数据库交互的能力。此实现允许Claude直接从对话中执行各种MongoDB操作，包括查询、聚合、数据操作（CRUD）和数据库管理。

概述

此MongoDB MCP服务器实现了模型上下文协议，以在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桌面或光标应用程序

设置

  1. 克隆此存储库（替换 ryaker 如果分叉，请使用您的用户名）：

    git clone git@github.com-personal:ryaker/mongodb-mcp-server.git
# Or use HTTPS if preferred
# git clone https://github.com/ryaker/mongodb-mcp-server.git
cd mongodb-mcp-server

  2. 安装依赖项：

    npm install

  3. 配置Claude桌面或光标：

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

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

    {
  "mcpServers": {
    "mongo-custom-server": { // You can name this key anything descriptive
      "command": "node",
      "args": ["/Volumes/Dev/localDev/MCPServers/CustomMongo_clean/mongo-mcp-server.js"], // <-- Make sure this path is correct!
      "env": {
        "MONGODB_URI": "mongodb+srv://your_username:your_password@your_cluster.mongodb.net/?retryWrites=true&w=majority", // <-- Your MongoDB connection string
        "DEFAULT_DATABASE": "YourDefaultDbName" // <-- Optional: Set a default database
      }
    }
  }
}
    • 重要提示： 替换占位符 MONGODB_URI 使用您实际的MongoDB连接字符串。确保URI中指定的用户具有您要执行的操作所需的权限。
    • 这 DEFAULT_DATABASE 是可选的。如果设置，操作将以该数据库为目标，除非被覆盖 database 工具调用中的参数。

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

工具参考

服务器公开了以下工具。大多数工具都接受可选 database 参数指定目标数据库，否则将使用 DEFAULT_DATABASE 在环境变量中设置。

查询与阅读

  1. aggregate：运行MongoDB聚合管道。
    • collection （string，必填）：集合的名称。
    • pipeline （数组，必填）：聚合管道阶段。
    • database （字符串，可选）：目标数据库。
  2. sample：获取随机样本文件。
    • collection （string，必填）：集合的名称。
    • count （数量，可选，默认值：5，最大值：10）：要采样的文档数量。
    • database （字符串，可选）：目标数据库。
  3. explain：获取聚合管道的执行计划。
    • collection （string，必填）：集合的名称。
    • pipeline （数组，必填）：聚合管道阶段。
    • database （字符串，可选）：目标数据库。
  4. find：查找与查询匹配的文档。
    • collection （string，必填）：集合的名称。
    • filter （对象，可选，默认值：｛｝）：查询筛选器。
    • projection （对象，可选，默认值：｛｝）：要包含/排除的字段。
    • limit （数字，可选，默认值：10，最大值：100）：要返回的最大文档数。
    • sort （对象，可选，默认值：｛｝）：排序条件。
    • database （字符串，可选）：目标数据库。
  5. findOne：查找与查询匹配的单个文档。
    • collection （string，必填）：集合的名称。
    • filter （对象，必填）：查询筛选器。
    • projection （对象，可选，默认值：｛｝）：要包含/排除的字段。
    • database （字符串，可选）：目标数据库。
  6. count：统计与查询匹配的文档。
    • collection （string，必填）：集合的名称。
    • filter （对象，可选，默认值：｛｝）：查询筛选器。
    • database （字符串，可选）：目标数据库。
  7. distinct：获取字段的不同值。
    • collection （string，必填）：集合的名称。
    • field （字符串，必填）：字段名称。
    • filter （对象，可选，默认值：｛｝）：查询筛选器。
    • database （字符串，可选）：目标数据库。

数据操作（写入/删除）

  1. insertOne：插入单个文档。
    • collection （string，必填）：集合的名称。
    • document （对象，必填）：要插入的文档。
    • database （字符串，可选）：目标数据库。
  2. insertMany：插入多个文档。
    • collection （string，必填）：集合的名称。
    • documents （array，必填）：文档数组。
    • database （字符串，可选）：目标数据库。
  3. updateOne：更新单个文档。
    • collection （string，必填）：集合的名称。
    • filter （对象，必填）：筛选以选择文档。
    • update （object，必填）：更新操作（例如。， $set).
    • upsert （布尔值，可选，默认值：false）：如果找不到则创建？
    • database （字符串，可选）：目标数据库。
  4. updateMany：更新多个文档。
    • collection （string，必填）：集合的名称。
    • filter （object，必填）：筛选以选择文档。
    • update （object，必填）：更新操作。
    • database （字符串，可选）：目标数据库。
  5. deleteOne：删除单个文档。
    • collection （string，必填）：集合的名称。
    • filter （对象，必填）：筛选以选择文档。
    • database （字符串，可选）：目标数据库。
  6. deleteMany：删除多个文档。
    • collection （string，必填）：集合的名称。
    • filter （object，必填）：筛选以选择文档。
    • database （字符串，可选）：目标数据库。

数据库/集合管理

  1. listCollections：列出数据库中的所有集合。
    • nameOnly （boolean，可选，默认值：false）：只返回名称？
    • database （字符串，可选）：目标数据库。
  2. listDatabases：列出服务器上的所有数据库。
    • nameOnly （boolean，可选，默认值：true）：只返回名称？
  3. dropCollection：删除整个收藏。
    • collection （string，必填）：要删除的集合的名称。
    • confirm （布尔值，必填）：必须是 true 确认删除。
    • database （字符串，可选）：目标数据库。

使用示例

查询数据：

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 'test@example.com'.
Claude: (Calls 'findOne' with collection='users', filter={email: 'test@example.com'})

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: 'alice@example.com' }
Claude: (Calls 'insertOne' with collection='users', document={ name: 'Alice', email: 'alice@example.com' })

User: Update the user with email 'alice@example.com' to set their status to 'active'.
Claude: (Calls 'updateOne' with collection='users', filter={email: 'alice@example.com'}, 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列表）。检查服务器日志(console.error)通过克劳德桌面/光标日志。
  • 工具未找到/正在工作：确保服务器正在运行，并在Claude Desktop/Cursor中正确配置。检查MCP服务器路径是否正确。重新启动Claude/Cursor。
  • 权限错误：查看MongoDB用户的角色和权限。

许可证

MIT许可证

致谢

相关 MCP