MongoDB MCP 服务器

Python 快速API FastMCP MongoDB Docker

强大的模型上下文协议 (MCP) 服务器实现，可通过标准化协议与 MongoDB 数据库进行无缝交互。

作者

拉斯塔利昂

Related MCP server: MongoDB

大纲

该 MCP 服务器实现提供了一个强大的接口，可以通过模型上下文协议与 MongoDB 数据库进行交互。它通过异步/等待模式和错误处理为数据库、集合和文档的操作提供可靠的支持。

特征

全面支持 MongoDB CRUD 操作
处理与 MongoDB 的安全连接
异步/等待模式以实现最佳性能
全面的错误处理
Docker 支持，轻松部署
使用类型提示执行查询
支持服务器发送事件 (SSE) 以实现实时更新

快速入门

用作 CLI 工具

# 저장소 복제
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 运行

# UVX가 설치된 경우
uvx mongo-mcp-server

# SSE 트랜스포트 모드
uvx mongo-mcp-server --transport=sse

直接运行 Python

# 저장소 복제
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

# 저장소 복제
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 是一个可以让你轻松管理各种环境中的服务的工具。

# 등록 스크립트에 실행 권한 부여
chmod +x uvx-register.sh

# UVX에 서비스 등록
./uvx-register.sh

# 서비스 시작
uvx start mongo-mcp

# 상태 확인
uvx status mongo-mcp

# 로그 확인
uvx logs mongo-mcp

有关详细信息，请参阅UVX 指南。

环境变量

运行服务器之前，请设置以下环境变量：

# 필수
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 - 服务器发送事件端点
消息处理： POST /messages - 消息处理端点

IDE 集成

VS Code 设置

将以下内容添加到您的 VS Code settings.json：

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "mongodbUri",
        "description": "MongoDB 연결 URI"
      }
    ],
    "servers": {
      "mongodb": {
        "command": "mongo-mcp-server",
        "args": [
          "--mongodb-url",
          "$(mongodbUri)"
        ],
        "env": {}
      }
    }
  }
}

克劳德或其他人工智能助手

为 Claude 或其他 AI 助手配置您的 MCP 服务器，如下所示：

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

可用工具

工具名称	解释
`listCollections`	列出数据库中所有可用的集合
`find`	使用 MongoDB 查询语法检索集合中的文档
`insertOne`	将单个文档插入集合
`updateOne`	更新集合中的单个文档
`deleteOne`	从集合中删除单个文档
`indexes`	列出集合中的所有索引
`createIndex`	在集合中创建新索引
`dropIndex`	从集合中删除现有索引

高级用法

添加自定义工具

在app/tools/documents/或app/tools/collection/中创建一个新工具：

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

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

from .documents.my_new_tool import MyNewTool

# ToolRegistry.__init__ 메서드 내에서
self.register_tool(MyNewTool())

安装和部署 CLI 工具

您可以通过在 PyPI 上将其注册为包来使其在全球范围内可用：

# 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 基础镜像
亚洲/首尔时区
MongoDB 4.4 实例
用于数据库存储的持久卷
对两种服务进行健康检查
自动化网络配置

执照

该项目根据 MIT 许可证分发 - 有关详细信息，请参阅LICENSE文件。

MongoDB MCP Server