Servidor MongoDB MCP

Un servidor de Protocolo de Contexto de Modelo que permite a los LLM interactuar con bases de datos MongoDB. Este servidor proporciona capacidades para inspeccionar esquemas de colección y ejecutar operaciones MongoDB a través de una interfaz estandarizada.

Manifestación

Características principales

Manejo inteligente de ObjectId

Conversión inteligente entre identificadores de cadena y ObjectId de MongoDB
Configurable con el parámetro objectIdMode :
- "auto" : Convertir según los nombres de campo (predeterminado)
- "none" : Sin conversión
- "force" : fuerza todos los campos de ID de cadena a ObjectId

Configuración flexible

Variables de entorno :
- MCP_MONGODB_URI : URI de conexión de MongoDB
- MCP_MONGODB_READONLY : Habilita el modo de solo lectura cuando se establece en "verdadero"
Opciones de línea de comandos :
- --read-only o -r : Conectarse en modo de solo lectura

Modo de solo lectura

Protección contra operaciones de escritura (actualizar, insertar, crear índice)
Utiliza la preferencia de lectura secundaria de MongoDB para un rendimiento óptimo
Ideal para conectarse de forma segura a bases de datos de producción

Operaciones de MongoDB

Operaciones de lectura :
- Consultar documentos con análisis de plan de ejecución opcional
- Ejecutar canalizaciones de agregación
- Contar documentos que coinciden con los criterios
- Obtener información del esquema de colección
Operaciones de escritura (cuando no está en modo de solo lectura):
- Actualizar documentos
- Insertar nuevos documentos
- Crear índices

Integración de LLM

Finalización de colecciones para una mejor interacción LLM
Inferencia de esquemas para una mejor comprensión del contexto
Análisis de recopilación de datos para obtener información

Instalación

Instalación global

npm install -g mcp-mongo-server

Para el desarrollo

# Clone repository
git clone https://github.com/kiliczsh/mcp-mongo-server.git
cd mcp-mongo-server

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

Uso

Uso básico

# Start server with MongoDB URI
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database

# Connect in read-only mode
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only

Variables de entorno

Puede configurar el servidor usando variables de entorno, lo que es particularmente útil para pipelines de CI/CD, contenedores Docker o cuando no desea exponer detalles de conexión en los argumentos del comando:

# Set MongoDB connection URI
export MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database"

# Enable read-only mode
export MCP_MONGODB_READONLY="true"

# Run server (will use environment variables if no URI is provided)
npx -y mcp-mongo-server

Uso de variables de entorno en la configuración de Claude Desktop:

{
  "mcpServers": {
    "mongodb-env": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

Uso de variables de entorno con Docker:

docker run -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" \
           -e MCP_MONGODB_READONLY="true" \
           mcp-mongo-server

Integración con Claude Desktop

Configuración manual

Agregue la configuración del servidor al archivo de configuración de Claude Desktop:

MacOS : ~/Library/Application Support/Claude/claude_desktop_config.json Windows : %APPDATA%/Claude/claude_desktop_config.json

Enfoque de argumentos de línea de comandos:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

Enfoque de variables ambientales:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database"
      }
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

Uso del paquete de GitHub:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

Integración con Windsurf y Cursor

El servidor MongoDB MCP se puede utilizar con Windsurf y Cursor de forma similar a Claude Desktop.

Configuración de windsurf

Añade el servidor a tu configuración de Windsurf:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

Configuración del cursor

Para Cursor, agregue la configuración del servidor a sus configuraciones:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

También puede utilizar el enfoque de variables de entorno con Windsurf y Cursor, siguiendo el mismo patrón que se muestra en la configuración de Claude Desktop.

Instalación automatizada

Uso de herrería :

npx -y @smithery/cli install mcp-mongo-server --client claude

Usando mcp-get :

npx @michaellatman/mcp-get@latest install mcp-mongo-server

Herramientas disponibles

Operaciones de consulta

consulta : Ejecutar consultas MongoDB
{ collection: "users", filter: { age: { $gt: 30 } }, projection: { name: 1, email: 1 }, limit: 20, explain: "executionStats" // Optional }
agregado : ejecutar canalizaciones de agregación
{ collection: "orders", pipeline: [ { $match: { status: "completed" } }, { $group: { _id: "$customerId", total: { $sum: "$amount" } } } ], explain: "queryPlanner" // Optional }
count : contar documentos coincidentes
{ collection: "products", query: { category: "electronics" } }

Operaciones de escritura

actualización : Modificar documentos
{ collection: "posts", filter: { _id: "60d21b4667d0d8992e610c85" }, update: { $set: { title: "Updated Title" } }, upsert: false, multi: false }
Insertar : Agregar nuevos documentos
{ collection: "comments", documents: [ { author: "user123", text: "Great post!" }, { author: "user456", text: "Thanks for sharing" } ] }
createIndex : Crea índices de colección
{ collection: "users", indexes: [ { key: { email: 1 }, unique: true, name: "email_unique_idx" } ] }

Operaciones del sistema

serverInfo : Obtener detalles del servidor MongoDB
{ includeDebugInfo: true // Optional }

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser complicada. Utilice el Inspector MCP para una mejor visibilidad:

npm run inspector

Esto proporcionará una URL para acceder a las herramientas de depuración en su navegador.

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.

MongoDB

Integrations