MCP 服务器

MongoDB MCP Server

一个协议服务器，使像 Claude 这样的大型语言模型能够与 MongoDB 数据库交互，在 Cursor 中通过自然语言提供模式探索、聚合查询和数据分析工具。

数据库

搜索

开发者工具

访问服务器

README

🗄️ 用于 LLMS 的 MongoDB MCP 服务器

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

📚 什么是模型上下文协议 (MCP)？

模型上下文协议 (MCP) 是 Anthropic 开发的开放标准，它为 AI 系统连接外部数据源和工具创建了一种通用方式。 MCP 建立了一个标准化的通信通道，连接：

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

MCP 的主要优势：

通用访问：为 AI 助手提供一个单一协议来查询来自各种来源的数据
标准化连接：一致地处理身份验证、使用策略和数据格式
可持续的生态系统：促进可在多个 LLM 客户端之间重复使用的连接器

✨ 特性

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

📋 前提条件

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

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

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

node --version  # 应该显示 v18.0.0 或更高版本

🚀 快速开始

要开始使用，请找到您的 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 集成

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

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

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

测试沙箱设置

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

使用 Docker Compose 启动 MongoDB：

docker-compose up -d

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

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"
      ]
    }
  }
}

测试沙箱数据结构

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

Users

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

Products

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

Orders

带有项目的订单详细信息
用户引用
运输和付款信息
状态跟踪

🎯 示例提示

尝试使用 Claude 的这些提示来探索该功能：

基本操作

"数据库中有哪些集合可用？"
"显示 users 集合的模式"
"查找旧金山的所有用户"

高级查询

"查找所有有库存且价格低于 1000 美元的电子产品"
"显示来自用户 john@example.com 的所有订单"
"列出评级高于 4.5 的产品"

索引管理

"users 集合上存在哪些索引？"
"在 products 集合上为 'category' 字段创建一个索引"
"列出所有集合中的所有索引"

文档操作

"在 products 集合中插入一个名为 'Gaming Laptop' 的新产品"
"将 ID 为 X 的订单状态更新为 'shipped'"
"查找并删除所有缺货的产品"

📝 可用工具

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

查询工具

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

索引工具

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

🛠️ 开发

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

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

要设置开发环境：

# 安装依赖
npm install

# 构建项目
npm run build

# 在开发模式下运行
npm run dev

# 运行测试
npm test

🔒 安全注意事项

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

创建一个专用的 MongoDB 用户，并具有满足您的用例所需的最低权限
切勿在生产环境中使用管理员凭据
启用访问日志记录以进行审计
在集合上设置适当的读/写权限
使用连接字符串参数来限制访问（例如，readPreference=secondary）
考虑 IP 允许列表以限制数据库访问

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

🌐 工作原理

MongoDB MCP 服务器：

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

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

📦 部署

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

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

❓ 故障排除

常见问题

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