🗄️ MongoDB MCP Server for LLMS

🗄️ 面向 LLM 的 MongoDB MCP 服务

一种 Model Context Protocol（MCP）服务，可让大模型直接与 MongoDB 数据库交互。通过自然语言无缝查询集合、检查架构并管理数据。

📚 什么是 Model Context Protocol（MCP）？

Model Context Protocol（MCP）是由 Anthropic 开发的一项开放标准，为 AI 系统连接外部数据源和工具提供通用方式。MCP 在以下各方之间建立标准化通信渠道：

• MCP 客户端：使用数据的 AI 助手，例如 Claude（如 Claude Desktop、Cursor.ai）
• MCP 服务：提供数据和功能的服务（如这个 MongoDB 服务）

MCP 的主要优势：

• 通用访问：为 AI 助手提供统一协议，以便从各种来源查询数据
• 标准化连接：以一致的方式处理身份验证、使用政策和数据格式
• 可持续生态系统：推动可在多个 LLM 客户端间使用的可复用连接器

✨ 功能

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

📋 前提条件

开始之前，请确保你具备以下条件：

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

运行以下命令，验证 Node.js 是否已安装：

node --version  # Should show v18.0.0 or higher

🚀 快速开始

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

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

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "mongo-mcp",
        "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin"
      ]
    }
  }
}

通过 Smithery 安装

Smithery.ai 是一个 MCP 服务注册平台，可简化服务发现和安装。要通过 Smithery 自动为 Claude Desktop 安装 MongoDB MCP 服务：

npx -y @smithery/cli install mongo-mcp --client claude

与 Cursor.ai 集成

要在 Cursor.ai 中使用 MongoDB MCP：

1. 打开 Cursor.ai，并前往 Settings > Features
2. 在功能面板中找到“MCP Servers”
3. 使用以下配置添加新的 MCP 服务：
   • 名称：mongodb
   • 命令：npx
   • 参数：mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin

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

测试沙箱设置

如果你没有可连接的 MongoDB 服务，并想创建一个示例沙箱，请按以下步骤操作：

1. 使用 Docker Compose 启动 MongoDB：

docker-compose up -d

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

npm run seed

配置 Claude Desktop

将以下配置添加到 Claude Desktop 配置文件中：

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

本地开发模式：

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": [
        "dist/index.js",
        "mongodb://root:example@localhost:27017/test?authSource=admin"
      ]
    }
  }
}

测试沙箱数据结构

种子脚本会创建三个包含示例数据的集合：

用户

• 个人信息（姓名、电子邮件、年龄）
• 包含坐标的嵌套地址
• 兴趣数组
• 会员日期

产品

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

订单

• 包含商品的订单详情
• 用户引用
• 配送和付款信息
• 状态跟踪

🎯 示例提示词

尝试使用这些提示词与 Claude 一起探索功能：

基本操作

"What collections are available in the database?"
"Show me the schema for the users collection"
"Find all users in San Francisco"

高级查询

"Find all electronics products that are in stock and cost less than $1000"
"Show me all orders from the user [email protected]"
"List the products with ratings above 4.5"

索引管理

"What indexes exist on the users collection?"
"Create an index on the products collection for the 'category' field"
"List all indexes across all collections"

文档操作

"Insert a new product with name 'Gaming Laptop' in the products collection"
"Update the status of order with ID X to 'shipped'"
"Find and delete all products that are out of stock"

📝 可用工具

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

查询工具

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

索引工具

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

🛠️ 开发

本项目使用以下技术构建：

• TypeScript，用于类型安全的开发
• MongoDB Node.js 驱动，用于数据库操作
• Zod，用于架构验证
• Model Context Protocol SDK，用于服务实现

设置开发环境：

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

🔒 安全注意事项

将此 MCP 服务与 MongoDB 数据库搭配使用时：

1. 创建专用的 MongoDB 用户，仅授予使用场景所需的最低权限
2. 切勿在生产环境中使用管理员凭据
3. 启用访问日志记录，用于审计
4. 为集合设置适当的读写权限
5. 使用连接字符串参数限制访问（例如，readPreference=secondary）
6. 考虑使用 IP 允许列表来限制数据库访问

⚠️ IMPORTANT：配置数据库访问时，务必遵循最小权限原则。

🌐 工作原理

MongoDB MCP 服务：

1. 使用提供的连接字符串连接到 MongoDB 数据库
2. 将 MongoDB 操作作为遵循 MCP 规范的工具公开
3. 使用 Zod 验证输入，确保类型安全和安全性
4. 执行查询，并将结构化数据返回给大模型客户端
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 Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📜 许可证

本项目基于 MIT License 授权，详情请参阅 LICENSE 文件。