MongoDB MCP 服务器

这是一个强大的 Model Context Protocol (MCP) 服务器实现，通过标准化协议提供与 MongoDB 数据库的顺畅交互。

作者

Rastalion

概述

此 MCP 服务器实现提供了通过 Model Context Protocol 与 MongoDB 数据库进行交互的强大接口。它通过 async/await 模式和错误处理稳定地支持对数据库、集合及文档的操作。

特性

• 完全支持 MongoDB CRUD 操作
• 安全处理与 MongoDB 的连接
• 为最佳性能采用异步 (async/await) 模式
• 全面的错误处理
• 支持 Docker 以方便部署
• 带有类型提示的查询执行
• 支持 SSE（Server-Sent Events）用于实时更新

快速开始

作为 CLI 工具使用

bash

克隆仓库

git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

开发模式安装

pip install -e .

本地运行 CLI 命令

mongo-mcp-server

使用 SSE 传输方式运行

mongo-mcp-server --transport=sse

指定 MongoDB URL

mongo-mcp-server --mongodb-url="mongodb://username:password@hostname:port/dbname"

查看帮助

mongo-mcp-server --help

通过 UVX 运行

bash

如果已安装 UVX

uvx mongo-mcp-server

SSE 传输模式

uvx mongo-mcp-server --transport=sse

直接用 Python 运行

bash

克隆仓库

git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

安装依赖

pip install -r requirements.txt

设置环境变量

export MONGODB_URL="mongodb://username:password@hostname:port/dbname?authSource=admin"

启动服务器

uvicorn app.main:app --host 0.0.0.0 --port 3000

使用 Docker

bash

克隆仓库

git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

使用 Docker Compose 构建并运行

docker-compose up -d

查看日志

docker-compose logs -f mongo-mcp

使用 UVX

UVX 是一个可以在多种环境中轻松管理服务的工具。

bash

给注册脚本添加执行权限

chmod +x uvx-register.sh

在 UVX 中注册服务

./uvx-register.sh

启动服务

uvx start mongo-mcp

检查状态

uvx status mongo-mcp

查看日志

uvx logs mongo-mcp

更多详细信息，请参阅 UVX 指南。

环境变量

在启动服务器之前，请设置以下环境变量：

bash

必需

MONGODB_URL="mongodb://username:password@hostname:port/dbname?authSource=admin"

可选 - 显示默认值

PORT=3000
MCP_TRANSPORT=http # http 或 sse

API 端点

• 健康检查: GET /health
• MCP API: GET /mcp - FastMCP 端点 (OpenAPI 文档)
• SSE 连接: GET /sse - Server-Sent Events 端点
• 消息处理: POST /messages - 消息处理端点

IDE 集成

VS Code 设置

在 VS Code 的 settings.json 文件中添加以下内容：

json
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "mongodbUri",
"description": "MongoDB 连接 URI"
}
],
"servers": {
"mongodb": {
"command": "mongo-mcp-server",
"args": [
"--mongodb-url",
"$(mongodbUri)"
],
"env": {}
}
}
}
}### Claude 或其他 AI 助手

为 Claude 或其他 AI 助手配置 MCP 服务器如下：

json
{
"mcp": {
"servers": {
"mongodb": {
"url": "http://localhost:3000/mcp"
}
}
}
}

可用工具

工具名称	描述
listCollections	查询数据库中所有可用的集合列表
find	使用 MongoDB 查询语法查询集合中的文档
insertOne	向集合插入单个文档
updateOne	更新集合中的单个文档
deleteOne	删除集合中的单个文档
indexes	查询集合的所有索引列表
createIndex	为集合创建新索引
dropIndex	删除集合中的现有索引

高级用法

添加自定义工具

1. 在 app/tools/documents/ 或 app/tools/collection/ 中创建新工具：

python
from ..base.tool import BaseTool

class MyNewTool(BaseTool):
@property
def name(self) -> str:
return "my_new_tool"

@property
def description(self) -> str:
    return "新工具的描述"

@property
def input_schema(self) -> Dict[str, Any]:
    return {
        "type": "object",
        "properties": {
            # 定义工具输入模式
        }
    }

async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
    # 实现工具执行逻辑
    pass

1. 在 app/tools/registry.py 中注册工具：

python
from .documents.my_new_tool import MyNewTool

在 ToolRegistry.init 方法内

self.register_tool(MyNewTool())

CLI 工具安装与部署

可以通过将包注册到 PyPI 来全局使用：

bash

检查 setup.py 并构建

python setup.py sdist bdist_wheel

上传包（需要 PyPI 账户）

twine upload dist/*

全局安装

pip install mongodb-mcp-bridge

从任何地方运行

mongodb-mcp-bridge

故障排除

• 服务器无法启动：使用 mongo-mcp-server --help 查看帮助
• MongoDB 连接问题：检查 --mongodb-url 参数是否正确
• 工具执行错误：检查工具实现和输入参数
• Docker 问题：使用 docker-compose logs mongo-mcp 查看日志

Docker 配置

Docker 设置包括以下内容：

• Python 3.12 基础镜像
• Asia/Seoul 时区
• MongoDB 4.4 实例
• 用于数据库存储的持久化卷
• 对两个服务的健康检查
• 自动化的网络配置

许可证

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