MCP Mongodb Wrapper

MongoDB MCP服务器

一个独立的模型上下文协议（MCP）服务器，为AI代理和聊天应用程序提供MongoDB数据库访问。

概述

此MCP服务器实现了完整的MCP协议（2024-11-05），允许AI代理通过标准化工具与MongoDB数据库进行交互。它支持SSE（服务器发送事件）和HTTP/JSON-RPC传输。

特性

• ✅ 完全支持MCP协议 -实现初始化、工具/列表、工具/调用、资源/列表和提示/列表
• ✅ MongoDB集成 -执行查询、列出集合并描述模式
• ✅ 双重运输 -支持SSE和HTTP传输
• ✅ Docker就绪 -包括Dockerfile和docker-compose.yml
• ✅ 健康检查 -内置健康监测
• ✅ 灵活的操作 -支持查找、插入、更新、删除和聚合操作

可用工具

服务器公开了三个MCP工具：

1. mongodb_query

对MongoDB集合执行各种操作。

输入：

{
  "collection": "users",
  "operation": "find",
  "filter": {"status": "active"},
  "limit": 10
}

支持的操作：

• find -查询文档（必填：收集、筛选，可选：限制）
• insert_one -插入文档（需要：收藏、文档）
• update_one -更新文档（需要：收集、筛选、更新）
• delete_one -删除文档（需要：收集、筛选）
• aggregate -运行聚合管道（需要：收集、管道）

输出： 查询结果为JSON对象数组

2. mongodb_list_collections

列出当前数据库中的所有集合。

输入： 无需

输出： 集合名称数组

3. mongodb_describe_collection

获取特定集合的详细信息，包括统计数据和示例文档。

输入：

{
  "collection": "users",
  "sample_size": 3
}

输出： 收集统计数据、字段名称和示例文档

快速开始

先决条件

• Docker和Docker Compose
• 现有的MongoDB数据库（服务器将连接到您的数据库）

1.配置数据库连接

复制示例环境文件并配置您的MongoDB连接：

cp env.sample .env

编辑 .env 使用您的MongoDB凭据：

MONGO_HOST=your_mongodb_host
MONGO_PORT=27017
MONGO_DB=your_database_name
MONGO_USER=your_username
MONGO_PASSWORD=your_password
MONGO_AUTH_SOURCE=admin

注： 如果你的MongoDB没有身份验证，请离开 MONGO_USER 和 MONGO_PASSWORD 空的。

2.启动服务器

docker compose up -d

这将启动端口8101上的MCP服务器。

3.验证它是否正在运行

# Check health
curl http://localhost:8101/health

# Expected: {"status":"healthy","database":"connected"}

4.测试MCP端点

# Test SSE endpoint
curl -H "Accept: text/event-stream" http://localhost:8101/mcp

# Test HTTP endpoint  
curl -X POST http://localhost:8101/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

配置

环境变量

服务器需要 .env 具有以下MongoDB连接设置的文件：

重要提示： 创建您的 .env 提供的文件 env.sample:

cp env.sample .env
# Then edit .env with your actual credentials

数据库连接

服务器使用中指定的凭据连接到您现有的MongoDB数据库 .env 文件。确保：

1. 您的MongoDB服务器可以从Docker容器访问
2. 用户对数据库具有适当的权限
3. 防火墙规则允许连接
4. 如果MongoDB位于同一主机上，请使用 host.docker.internal 而不是 localhost
5. 对于没有身份验证的MongoDB，请离开 MONGO_USER 和 MONGO_PASSWORD 空

使用AI代理

使用Python库从mcp连接

from mcp_use import MCPClient, MCPAgent
from langchain_openai import ChatOpenAI

# Create MCP client
client = MCPClient.from_dict({
    "mcpServers": {
        "MongoDB": {
            "url": "http://localhost:8101/mcp",
            "headers": {}
        }
    }
})

# Create agent
llm = ChatOpenAI(model="gpt-4")
agent = MCPAgent(llm=llm, client=client)

# Use it
result = agent.run("Show me all collections in the database")

LLM选择的重要注意事项

为了获得最佳的工具调用结果，请使用：

• ✅ OpenAI： gpt-4、gpt-4o、gpt-40-mini（优秀）
• ✅ 奥拉马： 骆驼3.1，骆驼3.2，米斯特拉尔（良好）
• ⚠️ 避免： qwen2.5:7b（有限的工具调用支持）

示例用法

连接后，您可以使用MCP工具与MongoDB数据库进行交互：

# List all collections
agent.run("What collections are available in the database?")

# Describe a collection
agent.run("Show me information about the users collection")

# Query data
agent.run("Find all users where status is active, limit to 10 results")

# Run aggregation
agent.run("Aggregate users by department and count them")

操作示例

查找文档

{
  "collection": "users",
  "operation": "find",
  "filter": {"age": {"$gte": 18}},
  "limit": 50
}

插入文档

{
  "collection": "users",
  "operation": "insert_one",
  "document": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
  }
}

更新文档

{
  "collection": "users",
  "operation": "update_one",
  "filter": {"email": "john@example.com"},
  "update": {"$set": {"age": 31}}
}

删除文档

{
  "collection": "users",
  "operation": "delete_one",
  "filter": {"email": "john@example.com"}
}

聚合管道

{
  "collection": "orders",
  "operation": "aggregate",
  "pipeline": [
    {"$match": {"status": "completed"}},
    {"$group": {"_id": "$customer_id", "total": {"$sum": "$amount"}}},
    {"$sort": {"total": -1}},
    {"$limit": 10}
  ]
}

API终点

发展

不使用Docker运行

# Install dependencies
pip install fastapi uvicorn pymongo pydantic

# Set environment variables (or create .env file)
export MONGO_HOST=localhost
export MONGO_PORT=27017
export MONGO_USER=your_username
export MONGO_PASSWORD=your_password
export MONGO_DB=your_database

# Run server
python server.py

更改后重建

docker compose down
docker compose build --no-cache
docker compose up -d

故障排除

连接被拒绝

如果您遇到连接错误，请确保：

1. 您的MongoDB服务器正在运行并可访问
2. 这 .env 文件包含正确的数据库凭据
3. 端口8101未使用： lsof -i :8101
4. MCP服务器运行正常： curl http://localhost:8101/health
5. 如果MongoDB位于本地主机上，请尝试使用 host.docker.internal 作为主持人

工具调用不起作用

如果AI代理发现了工具，但没有调用它们：

1. 检查LLM模型是否支持工具调用
2. 使用明确的提示：“调用mongodb_list_collections工具”
3. 考虑切换到OpenAI（gpt-4o-mini）

数据库连接问题

检查MCP服务器日志：

docker compose logs mongodb-mcp-server

从主机手动测试数据库连接：

mongosh --host your_mongo_host --port 27017 -u your_username -p

检查MongoDB是否允许从Docker连接：

• 验证MongoDB是否仅绑定到127.0.0.1（检查 bindIp 在 mongod.conf)
• 确保身份验证配置正确
• 检查防火墙规则

身份验证问题

对于具有身份验证的MongoDB：

# In .env file
MONGO_USER=admin
MONGO_PASSWORD=your_password
MONGO_AUTH_SOURCE=admin

对于没有身份验证的MongoDB：

# In .env file
MONGO_USER=
MONGO_PASSWORD=

安全考虑

⚠️ 重要安全指南：

1. 永不承诺 .env 文件 -添加到 .gitignore
2. 使用强密码 适用于MongoDB用户
3. 使用环境变量 或生产中的秘密管理
4. 实施身份验证 对于MCP端点
5. 限制数据库操作 （尽可能使用只读用户）
6. 启用TLS/SSL 用于生产环境中的MongoDB连接
7. 限制网络访问 到MongoDB服务器
8. 验证所有输入 在执行操作之前
9. 使用基于角色的访问控制 在MongoDB中
10. 监控并记录所有操作

与主应用程序集成

该MCP服务器可以独立使用，也可以与主MCP管理系统集成使用。

独立使用

独立运行并从任何兼容MCP的客户端连接。

与MCP管理系统集成

添加到主应用程序的设置中：

Name: MongoDB MCP Server
Type: HTTP/HTTPS
Category: database
URL: http://mongodb-mcp-server:8101/mcp

与PostgreSQL版本的差异

• 端口： 使用8101而不是8100
• 操作： 支持MongoDB特定的操作（聚合管道、基于文档的查询）
• 数据格式： 返回BSON/JSON文档，而不是表行
• 架构： 集合而不是表，灵活的模式
• 查询语言： MongoDB查询语法而不是SQL

许可证

MIT许可证

支持

有关问题或疑问，请查看：

1. 服务器日志： docker compose logs mongodb-mcp-server
2. 健康终点： curl http://localhost:8101/health
3. MongoDB连接：测试 mongosh 或MongoDB指南针

技术细节

• 协议： MCP 2024-11-05
• 运输： SSE（首选）和HTTP/JSON-RPC
• 服务器： FastAPI+Uvicorn
• 数据库驱动程序： 皮蒙哥语
• 集装箱： Python 3.11-slim
• BSON处理： 用途 bson.json_util 为了正确序列化

MongoDB查询语法参考

基本查询

• {"field": "value"} -完全匹配
• {"field": {"$gt": 100}} -大于
• {"field": {"$gte": 100}} -大于或等于
• {"field": {"$lt": 100}} -小于
• {"field": {"$lte": 100}} -小于或等于
• {"field": {"$ne": "value"}} -不相等
• {"field": {"$in": ["val1", "val2"]}} -阵列内

逻辑运算符

• {"$and": [{...}, {...}]} -和条件
• {"$or": [{...}, {...}]} -OR条件
• {"$not": {...}} -非条件

更新操作员

• {"$set": {"field": "value"}} -设置字段值
• {"$unset": {"field": ""}} -删除字段
• {"$inc": {"field": 1}} -增量字段
• {"$push": {"array": "item"}} -添加到数组

______________________________________________________________________

内置❤️ 模型上下文协议生态系统