🗄️ LLMS 的 MongoDB MCP 服务器

模型上下文协议 (MCP) 服务器，使 LLM 能够直接与 MongoDB 数据库交互。通过自然语言无缝查询集合、检查架构并管理数据。

📚 什么是模型上下文协议（MCP）？

模型上下文协议 (MCP) 是由 Anthropic 开发的一项开放标准，旨在为 AI 系统创建一种通用的连接方式，以便与外部数据源和工具进行连接。MCP 在以下各项之间建立了标准化的通信渠道：

• MCP 客户端：像 Claude 这样的使用数据的 AI 助手（例如 Claude Desktop、Cursor.ai）
• MCP 服务器：公开数据和功能的服务（例如此 MongoDB 服务器）

MCP 的主要优点：

• 通用访问：为人工智能助手提供单一协议，以便从各种来源查询数据
• 标准化连接：一致地处理身份验证、使用策略和数据格式
• 可持续生态系统：推广可跨多个 LLM 客户端工作的可重复使用连接器

✨ 特点

• 🔍 集合模式检查
• 📊 文档查询和过滤
• 📈 索引管理
• 📝 文档操作（插入、更新、删除）
• 🔒 通过连接字符串实现安全的数据库访问
• 📋 全面的错误处理和验证

📋 先决条件

在开始之前，请确保您已：

• Node.js （v18 或更高版本）
• MongoDB实例（本地或远程）
• 像Claude Desktop或Cursor.ai这样的 MCP 客户端

您可以通过运行以下命令来验证您的 Node.js 安装：

🚀 快速入门

首先，找到您的 MongoDB 连接 URL，并将此配置添加到您的 Claude Desktop 配置文件中：

MacOS ： ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows ： %APPDATA%/Claude/claude_desktop_config.json

通过 Smithery 安装

Smithery.ai是一个 MCP 服务器注册平台，可简化 MCP 服务器的发现和安装。要通过 Smithery 自动为 Claude Desktop 安装 MongoDB MCP 服务器，请执行以下操作：

Cursor.ai集成

要将 MongoDB MCP 与 Cursor.ai 一起使用：

1. 打开 Cursor.ai 并导航至“设置”>“功能”
2. 在功能面板中查找“MCP 服务器”
3. 添加一个新的 MCP 服务器，配置如下：
   • 名称： mongodb
   • 命令： npx
   • 参数： mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin

注意：Cursor 目前仅在 Composer 中的 Agent 功能中支持 MCP 工具。

测试沙盒设置

如果您没有可连接的 MongoDB 服务器并且想要创建示例沙盒，请按照以下步骤操作：

1. 使用 Docker Compose 启动 MongoDB：

2. 使用测试数据填充数据库：

配置 Claude 桌面

将此配置添加到您的 Claude Desktop 配置文件：

MacOS ： ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows ： %APPDATA%/Claude/claude_desktop_config.json

本地开发模式：

测试沙盒数据结构

种子脚本使用示例数据创建三个集合：

用户

• 个人信息（姓名、电子邮件、年龄）
• 嵌套地址及坐标
• 一系列的兴趣
• 会员日期

产品

• 产品详情（名称、SKU、类别）
• 嵌套规范
• 价格和库存信息
• 标签和评分

订单

• 订单详情及商品
• 用户参考
• 运输和付款信息
• 状态跟踪

🎯 示例提示

尝试与 Claude 一起执行这些提示来探索其功能：

基本操作

高级查询

指数管理

文档操作

📝 可用工具

服务器提供了以下用于数据库交互的工具：

查询工具

• listCollections ：列出数据库中可用的集合
• find ：使用过滤和投影查询文档
• insertOne ：将单个文档插入集合
• updateOne ：更新集合中的单个文档
• deleteOne ：从集合中删除单个文档

索引工具

• createIndex ：在集合上创建新索引
• dropIndex ：从集合中删除索引
• indexes ：列出集合的索引

🛠️ 开发

该项目由以下部分构成：

• TypeScript 用于类型安全开发
• 用于数据库操作的 MongoDB Node.js 驱动程序
• Zod 用于模式验证
• 用于服务器实现的模型上下文协议SDK

设置开发环境：

🔒 安全注意事项

将此 MCP 服务器与您的 MongoDB 数据库一起使用时：

1. **创建专用的 MongoDB 用户，**并根据用例需要使用最少的权限
2. 切勿在生产环境中使用管理员凭据
3. 启用访问日志以用于审计目的
4. 对集合设置适当的读/写权限
5. 使用连接字符串参数来限制访问（例如readPreference=secondary ）
6. 考虑使用 IP 允许列表来限制数据库访问

⚠️重要提示：配置数据库访问时始终遵循最小特权原则。

🌐 工作原理

MongoDB MCP 服务器：

1. 使用提供的连接字符串连接到您的 MongoDB 数据库
2. 将 MongoDB 操作公开为遵循 MCP 规范的工具
3. 使用 Zod 验证输入以确保类型安全和保障
4. 执行查询并返回结构化数据给 LLM 客户端
5. 管理连接池和适当的错误处理

所有操作均经过适当的验证，以防止注入攻击等安全问题。

📦部署

您可以通过多种方式部署此 MCP 服务器：

• 通过 npx 本地（如快速入门中所示）
• 作为全局 npm 包： npm install -g @coderay/mongo-mcp-server
• 在 Docker 容器中（请参阅存储库中的 Dockerfile）
• 作为 Heroku、Vercel 或 AWS 等平台上的服务

❓ 故障排除

常见问题

1. 连接错误
   • 验证 MongoDB 连接字符串是否正确
   • 检查您的 MongoDB 服务器是否正在运行且可访问
   • 确保网络权限允许连接
2. 身份验证问题
   • 确认用户名和密码正确
   • 验证是否指定了身份验证数据库（通常为authSource=admin ）
   • 检查 MongoDB 是否需要 TLS/SSL 连接
3. 工具执行问题
   • 完全重启 Claude Desktop 或 Cursor.ai
   • 检查日志以获取详细的错误消息：
     # macOS tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
4. 性能问题
   • 考虑对经常查询的字段添加适当的索引
   • 使用投影来限制查询返回的数据
   • 使用 limit 和 skip 参数进行分页

获取帮助

如果您遇到问题：

• 查看MCP 文档
• 在我们的GitHub 存储库上提交问题

🤝 贡献

欢迎贡献代码！欢迎提交 Pull 请求。

1. 分叉存储库
2. 创建你的功能分支（ git checkout -b feature/amazing-feature ）
3. 提交您的更改（ git commit -m 'Add some amazing feature' ）
4. 推送到分支（ git push origin feature/amazing-feature ）
5. 打开拉取请求

📜 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。