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

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

Nombre de la herramienta	explicación
`listCollections`	Enumere todas las colecciones disponibles en la base de datos
`find`	Recuperar documentos en una colección mediante la sintaxis de consulta de MongoDB
`insertOne`	Insertar un solo documento en una colección
`updateOne`	Actualizar un solo documento en una colección
`deleteOne`	Eliminar un solo documento de una colección
`indexes`	Listar todos los índices de una colección
`createIndex`	Crear un nuevo índice en una colección
`dropIndex`	Eliminar un índice existente de una colección

Uso avanzado

Agregar herramientas personalizadas

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

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.

MongoDB MCP Server

Integrations