Mongo-MCP

Un servidor MCP para interactuar con una base de datos MongoDB.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Mongo-MCP

smithery badge Inglés | 简体中文

Un servicio de Protocolo de Chat de Máquina (MCP) para operaciones con MongoDB. Este servicio proporciona un conjunto completo de herramientas que permiten a los Modelos de Lenguaje de Gran Escala (LLMs) interactuar con bases de datos MongoDB mediante operaciones CRUD completas, tareas administrativas y funciones avanzadas.

Requisitos

  • Python 3.10 o superior
  • Un servicio de base de datos MongoDB en ejecución
  • Se recomienda usar uv para ejecutar el programa

🚀 Características

📊 Herramientas de Gestión de Bases de Datos

  • list_databases - Listar todas las bases de datos
  • create_database - Crear nueva base de datos
  • drop_database - Eliminar base de datos
  • get_database_stats - Obtener estadísticas de la base de datos

📦 Herramientas de Gestión de Colecciones

  • list_collections - Listar todas las colecciones en una base de datos
  • create_collection - Crear nueva colección (con configuraciones opcionales)
  • drop_collection - Eliminar colección
  • rename_collection - Renombrar colección
  • get_collection_stats - Obtener estadísticas de la colección

📄 Operaciones CRUD de Documentos

  • insert_document - Insertar un solo documento
  • insert_many_documents - Insertar múltiples documentos en lote
  • find_documents - Consultar documentos (admite ordenamiento, proyección, límite)
  • find_one_document - Consultar un solo documento
  • count_documents - Contar documentos que coinciden con la consulta
  • update_document - Actualizar documentos (individual o en lote)
  • replace_document - Reemplazar documento
  • delete_document - Eliminar documentos (individual o en lote)

🔍 Herramientas de Gestión de Índices

  • list_indexes - Listar todos los índices de una colección
  • create_index - Crear índice regular
  • create_text_index - Crear índice de búsqueda de texto
  • create_compound_index - Crear índice compuesto
  • drop_index - Eliminar índice
  • reindex_collection - Reconstruir todos los índices de una colección

📈 Operaciones de Agregación

  • aggregate_documents - Ejecutar operaciones de pipeline de agregación
  • distinct_values - Obtener valores distintos para un campo

🔧 Herramientas de Monitoreo y Administración

  • get_server_status - Obtener estado del servidor MongoDB
  • get_replica_set_status - Obtener estado del conjunto de réplicas
  • ping_database - Probar conexión a la base de datos
  • test_mongodb_connection - Prueba de conexión integral
  • get_connection_details - Obtener información detallada de la conexión

🛠️ Stack Tecnológico

  • Python: Lenguaje de programación principal
  • FastMCP: SDK de Python para MCP con generación automática de definiciones de herramientas
  • PyMongo: Controlador oficial de MongoDB para Python
  • uv: Herramienta moderna de gestión de paquetes de Python

Uso

Ejecutar directamente con uvx

uvx run mongo-mcp

El servidor utiliza el método de transporte stdio, lo que lo hace adecuado para la integración con clientes MCP que admiten este método de transporte.

Ejemplo de Configuración en Cursor

Si usas Cursor como tu entorno de desarrollo, puedes agregar la siguiente configuración a tu archivo .cursor/mcp.json para depuración local:

{
    "mcpServers": {
        "mongo-mcp": {
            "command": "uvx",
            "args": [
                "mongo-mcp"
            ],
            "env": {
                "MONGODB_URI": "mongodb://localhost:27017",
                "MONGODB_DEFAULT_DB": "your_database_name",
                "LOG_LEVEL": "INFO"
            }
        }
    }
}

Variables de Entorno

Configuración Básica

  • MONGODB_URI: Cadena de conexión de MongoDB (predeterminado: "mongodb://localhost:27017")
  • MONGODB_DEFAULT_DB: Nombre de base de datos predeterminado (opcional)

Configuración del Pool de Conexiones

  • MONGODB_MIN_POOL_SIZE: Tamaño mínimo del pool de conexiones (predeterminado: 0)
  • MONGODB_MAX_POOL_SIZE: Tamaño máximo del pool de conexiones (predeterminado: 100)
  • MONGODB_MAX_IDLE_TIME_MS: Tiempo máximo de inactividad en milisegundos (predeterminado: 30000)

Configuración de Tiempos de Espera

  • MONGODB_SERVER_SELECTION_TIMEOUT_MS: Tiempo de espera de selección del servidor (predeterminado: 30000)
  • MONGODB_SOCKET_TIMEOUT_MS: Tiempo de espera del socket (predeterminado: 0 - sin tiempo de espera)
  • MONGODB_CONNECT_TIMEOUT_MS: Tiempo de espera de conexión (predeterminado: 20000)

Configuración de Seguridad

  • MONGODB_TLS_ENABLED: Habilitar conexión TLS (predeterminado: false)
  • MONGODB_AUTH_SOURCE: Fuente de autenticación (predeterminado: admin)
  • MONGODB_AUTH_MECHANISM: Mecanismo de autenticación (SCRAM-SHA-1, SCRAM-SHA-256, etc.)

Configuración de Rendimiento

  • MONGODB_READ_PREFERENCE: Preferencia de lectura (predeterminado: primary)
  • MONGODB_WRITE_CONCERN_W: Preocupación de escritura (predeterminado: 1)
  • MONGODB_READ_CONCERN_LEVEL: Nivel de preocupación de lectura (predeterminado: local)

Configuración de Registros

  • LOG_LEVEL: Nivel de registro (predeterminado: "INFO")
    • Valores disponibles: DEBUG, INFO, WARNING, ERROR, CRITICAL
  • LOG_MAX_FILE_SIZE: Tamaño máximo del archivo de registro en bytes (predeterminado: 10MB)
  • LOG_BACKUP_COUNT: Número de archivos de registro de respaldo (predeterminado: 5)

Indicadores de Funcionalidades

  • ENABLE_DANGEROUS_OPERATIONS: Habilitar operaciones potencialmente peligrosas (predeterminado: false)
  • ENABLE_ADMIN_OPERATIONS: Habilitar operaciones administrativas (predeterminado: true)
  • ENABLE_INDEX_OPERATIONS: Habilitar operaciones de índices (predeterminado: true)

Guía de Desarrollo

  1. Clonar el repositorio
git clone https://github.com/441126098/mongo-mcp.git
cd mongo-mcp
  1. Instalar dependencias de desarrollo
# Using uv (recommended)
uv sync

# Or using pip
pip install -e ".[dev]"
  1. Ejecutar pruebas
uv run pytest tests/ -v
  1. Estructura del Código
  • src/mongo_mcp/server.py: Implementación del servidor MCP
  • src/mongo_mcp/db.py: Implementación de operaciones principales de MongoDB
  • src/mongo_mcp/config.py: Gestión de configuración
  • src/mongo_mcp/tools/: Implementación de herramientas MCP
    • database_tools.py: Gestión de bases de datos y colecciones
    • document_tools.py: Operaciones CRUD de documentos
    • index_tools.py: Gestión de índices
    • aggregation_tools.py: Operaciones de agregación
    • admin_tools.py: Herramientas administrativas y de monitoreo
  • src/mongo_mcp/utils/: Módulos de utilidades
  • tests/: Casos de prueba

Pruebas

El proyecto incluye una cobertura de pruebas integral:

  • Pruebas unitarias para todos los módulos de herramientas
  • Pruebas de integración con MongoDB
  • Pruebas simuladas para pruebas de componentes aislados

Ejecutar el conjunto de pruebas:

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_tools.py

Registros

Los archivos de registro se almacenan en el directorio logs de forma predeterminada. El sistema de registro admite:

  • Niveles de registro configurables
  • Rotación de archivos basada en tamaño
  • Soporte de codificación UTF-8
  • Registro estructurado con nombres de funciones y números de línea

Licencia

MIT

Contribuciones

Se aceptan contribuciones mediante Issues y Pull Requests. Antes de enviar un PR, asegúrate de:

  1. Que todas las pruebas pasen (uv run pytest)
  2. Que se agreguen casos de prueba apropiados
  3. Que la documentación esté actualizada
  4. Que el código siga los patrones de estilo existentes