Servidor MCP de MongoDB

Una potente implementación de servidor de Protocolo de Contexto de Modelo (MCP) que proporciona una interacción fluida con las bases de datos MongoDB a través de un protocolo estandarizado.

Autor

Rastalion

Related MCP server: MongoDB

describir

Esta implementación de servidor MCP proporciona una interfaz poderosa para interactuar con una base de datos MongoDB a través del Protocolo de Contexto de Modelo. Proporciona soporte confiable para operaciones en bases de datos, colecciones y documentos con el patrón async/await y manejo de errores.

característica

• Soporte completo para operaciones CRUD de MongoDB

• Manejo de conexiones seguras a MongoDB

• Patrón asíncrono/en espera para un rendimiento óptimo

• Manejo integral de errores

• Compatibilidad con Docker para una implementación sencilla

• Ejecución de consultas con sugerencias de tipo

• Compatibilidad con eventos enviados por el servidor (SSE) para actualizaciones en tiempo real

Inicio rápido

Úselo como herramienta 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

Ejecutar a través de UVX

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

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

Ejecutar Python directamente

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

Usando 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

Uso de UVX

UVX es una herramienta que permite gestionar fácilmente servicios en diversos entornos.

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

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

# 서비스 시작
uvx start mongo-mcp

# 상태 확인
uvx status mongo-mcp

# 로그 확인
uvx logs mongo-mcp

Para obtener más información, consulte la Guía UVX .

Variables de entorno

Antes de ejecutar el servidor, configure las siguientes variables de entorno:

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

# 선택 - 기본값 표시
PORT=3000
MCP_TRANSPORT=http  # 'http' 또는 'sse'

Punto final de API

• Comprobar la salud : GET /health

• API de MCP : GET /mcp - Punto final de FastMCP (documentación de OpenAPI)

• Conexión SSE : GET /sse - Punto final de eventos enviados por el servidor

• Procesamiento de mensajes : POST /messages - Punto final de procesamiento de mensajes

Integración IDE

Configuración de VS Code

Agregue lo siguiente a su archivo settings.json de VS Code:

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

Claude u otro asistente de IA

Configure su servidor MCP para Claude u otros asistentes de IA de la siguiente manera:

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

Herramientas disponibles

Uso avanzado

Agregar herramientas personalizadas

1. Crea una nueva herramienta en app/tools/documents/ o 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

2. Registre la herramienta en app/tools/registry.py :

from .documents.my_new_tool import MyNewTool

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

Instalación e implementación de herramientas CLI

Puedes hacerlo disponible globalmente registrándolo como paquete en PyPI:

# setup.py 확인 후 빌드
python setup.py sdist bdist_wheel

# 패키지 업로드 (PyPI 계정 필요)
twine upload dist/*

# 전역 설치
pip install mongodb-mcp-bridge

# 어디서든 실행 가능
mongodb-mcp-bridge

Solución de problemas

• Si el servidor no se inicia : consulte la ayuda con mongo-mcp-server --help

• Problema de conexión de MongoDB : Verifique que --mongodb-url sea correcto

• Error de ejecución de la herramienta : Verifique la implementación de la herramienta y los parámetros de entrada

• Problema de Docker : comprobar registros con docker-compose logs mongo-mcp

Configuración de Docker

La configuración de Docker incluye:

• Imagen base de Python 3.12

• Zona horaria de Asia/Seúl

• Instancia de MongoDB 4.4

• Volúmenes persistentes para el almacenamiento de bases de datos

• Comprobación del estado de salud de ambos servicios

• Configuración de red automatizada

Licencia

Este proyecto se distribuye bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.