项目介绍
🗄️ MongoDB MCP Server for LLMS
这是一个模型上下文协议（MCP）服务器，使LLMs能够直接与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 # 应显示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自动安装MongoDB MCP Server for Claude Desktop：
npx -y @smithery/cli install mongo-mcp --client claude
Cursor.ai集成
要在Cursor.ai中使用MongoDB MCP：
- 打开Cursor.ai并导航至设置 > 功能
- 在功能面板中查找“MCP服务器”
- 添加一个新的MCP服务器，配置如下：
- 名称：
mongodb - 命令：
npx - 参数：
mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin
- 名称：
注意：Cursor目前仅支持Agent in Composer功能中的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、类别）
- 嵌套规格
- 价格和库存信息
- 标签和评分
订单
- 订单详情及项目
- 用户引用
- 运输和支付信息
- 状态跟踪
🎯 示例提示
尝试这些提示以探索功能：
基本操作
"数据库中有哪些集合？"
"显示用户集合的模式"
"查找所有在旧金山的用户"
高级查询
"查找所有在库且价格低于$1000的电子产品"
"显示来自用户john@example.com的所有订单"
"列出评分高于4.5的产品"
索引管理
"用户集合上存在哪些索引？"
"在产品集合上为'类别'字段创建索引"
"列出所有集合上的所有索引"
文档操作
"在产品集合中插入一个名为'游戏笔记本电脑'的新产品"
"更新ID为X的订单状态为'已发货'"
"查找并删除所有缺货的产品"
📝 可用工具
该服务器提供了这些工具用于数据库交互：
查询工具
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参数进行分页
获取帮助
遇到问题时：
🤝 贡献
欢迎贡献！请随时提交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文件。