MongoDB中间件

@1RB/mongo-mcp

0 Stars 804 次浏览 1RB 更新于 2026-08-23

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

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

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

该服务需要配置环境变量：MONGO_URI

服务介绍

🗄️ MongoDB MCP 服务器用于 LLM

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

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

模型上下文协议（MCP）是由 Anthropic 开发的一种开放标准，它创建了一种通用的方式，让 AI 系统能够连接到外部数据源和工具。MCP 在以下两者之间建立了一个标准化的通信通道：

MCP 客户端：如 Claude 这样的 AI 助手，它们消费数据（例如 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 集成

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

打开 Cursor.ai 并导航到设置 > 功能
在功能面板中查找“MCP 服务器”
添加一个新的 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"
      ]
    }
  }
}

测试沙盒数据结构

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

用户

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

产品

产品详情（名称、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 john@example.com"
"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数据库时：

创建具有最小权限的专用MongoDB用户，仅提供您用例所需的权限
切勿在生产环境中使用管理员凭据
启用访问日志记录以进行审计
为集合设置适当的读写权限
使用连接字符串参数限制访问（例如，readPreference=secondary）
考虑IP白名单以限制数据库访问

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

🌐 工作原理

MongoDB MCP服务器：

使用提供的连接字符串连接到您的MongoDB数据库
按照MCP规范将MongoDB操作暴露为工具
使用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 参数进行分页

获取帮助

如果您遇到问题：

查阅 MCP 文档
在我们的 GitHub 仓库提交问题

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

叉取仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开一个 Pull Request

📜 许可证

本项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

查看源码项目主页