MongoDB That Works

Un servidor MCP de MongoDB con descubrimiento de esquemas y validación de campos. Requiere una variable de entorno MONGODB_URI.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MongoDB MCP That Works

npm version npm downloads npm weekly downloads CI GitHub release license GitHub stars node

Un servidor MCP (Model Context Protocol) de MongoDB confiable con descubrimiento de esquemas integrado y validación de campos. Es un servidor MCP estándar sobre stdio, por lo que se conecta a cualquier cliente MCP: Claude Desktop, Claude Code, OpenAI Codex, Cursor, VS Code / GitHub Copilot, Zed y más.

Publicado en npm: @sourabhshegane/mongodb-mcp-that-works · Instalar con npx -y @sourabhshegane/mongodb-mcp-that-works

[!CAUTION] Este servidor se conecta a tu MongoDB con acceso completo de lectura/escritura al usuario y la base de datos que proporciones mediante MONGODB_URI, y expone herramientas de escritura (insertOne, updateOne, deleteOne) a cualquier cliente conectado. Solo regístralo con clientes MCP en los que confíes. Para entornos de alto riesgo, usa un usuario de MongoDB de solo lectura o una base de datos dedicada.

Características

  • 🔍 Descubrimiento de esquemas: Analiza automáticamente las estructuras de las colecciones
  • ✅ Validación de campos: Evita errores en los nombres de los campos
  • 📊 Soporte completo de MongoDB: Operaciones de find, aggregate, insert, update, delete
  • 🚀 Alto rendimiento: Pooling de conexiones eficiente y optimización de consultas
  • 🔐 Seguro: Soporte para MongoDB Atlas y autenticación
  • 🎯 Seguridad de tipos: Construido con TypeScript y validación Zod

Instalación

Instalar desde npm

npm install -g @sourabhshegane/mongodb-mcp-that-works

Configuración

Este es un servidor MCP estándar sobre stdio. Cualquier cliente MCP lo inicia con npx y le pasa dos variables de entorno:

VariableRequeridaDescripción
MONGODB_URISíCadena de conexión de MongoDB, p. ej. mongodb+srv://user:pass@cluster.mongodb.net/database
MONGODB_DATABASENoNombre de la base de datos por defecto (usa la base de datos de la URI si no se especifica)

Cada cliente a continuación usa el mismo comando de lanzamiento:

npx -y @sourabhshegane/mongodb-mcp-that-works@latest

La bandera -y confirma automáticamente la instalación para que el cliente nunca se quede esperando en un mensaje interactivo.

Seguridad: nunca confirmes una cadena de conexión real. Los ejemplos usan marcadores de posición o referencian variables de entorno (${env:...}, env_vars, ${input:...}) para que las credenciales no queden en el control de versiones.

Claude Desktop

Edita tu configuración de Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>",
        "MONGODB_DATABASE": "your_database_name"
      }
    }
  }
}

Claude Code

Agrégalo con la CLI (todo lo que esté después de -- es el comando del servidor):

claude mcp add mongodb --scope user \
  --env MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/<database> \
  -- npx -y @sourabhshegane/mongodb-mcp-that-works@latest

O confirma un .mcp.json a nivel de proyecto (los secretos se referencian con ${VAR}):

{
  "mcpServers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "${MONGODB_URI}",
        "MONGODB_DATABASE": "${MONGODB_DATABASE:-your_database_name}"
      }
    }
  }
}

Ámbitos: local → ~/.claude.json, project → .mcp.json, user → ~/.claude.json. Verifica con claude mcp list.

OpenAI Codex

Codex usa TOML (no JSON). Agrégalo a ~/.codex/config.toml (o a nivel de proyecto .codex/config.toml):

[mcp_servers.mongodb]
command = "npx"
args = ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"]
env = { MONGODB_URI = "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>", MONGODB_DATABASE = "your_database_name" }
startup_timeout_sec = 30

O reenvía variables desde tu shell en lugar de incrustarlas:

[mcp_servers.mongodb]
command = "npx"
args = ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"]
env_vars = ["MONGODB_URI", "MONGODB_DATABASE"]

O agrégalo con la CLI: codex mcp add mongodb -- npx -y @sourabhshegane/mongodb-mcp-that-works@latest. Verifica con codex mcp list.

Cursor

Ámbito de proyecto: .cursor/mcp.json (confírmalo para compartirlo con tu equipo). Ámbito global: ~/.cursor/mcp.json.

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "${env:MONGODB_URI}",
        "MONGODB_DATABASE": "${env:MONGODB_DATABASE}"
      }
    }
  }
}

VS Code / GitHub Copilot

Para una instalación rápida, haz clic en los botones a continuación. Después de instalar, reemplaza la cadena de conexión de marcador de posición en tu configuración:

Install with NPX in VS Code Install with NPX in VS Code Insiders

Nota: la clave raíz de VS Code es servers (otros clientes usan mcpServers), y type es obligatorio. .vscode/mcp.json:

{
  "servers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "${input:mongodb-uri}"
      }
    }
  },
  "inputs": [
    {
      "id": "mongodb-uri",
      "type": "promptString",
      "description": "MongoDB connection string",
      "password": true
    }
  ]
}

Zed

Agrégalo a settings.json (~/.config/zed/settings.json o .zed/settings.json):

{
  "mcp": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
      "env": {
        "MONGODB_URI": "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>"
      }
    }
  }
}

Herramientas disponibles

1. listCollections

Lista todas las colecciones en la base de datos.

// Example
mcp.listCollections({ filter: {} })

2. find

Busca documentos en una colección con filtrado, ordenamiento y paginación.

// Example
mcp.find({
  collection: "users",
  filter: { status: "active" },
  sort: { createdAt: -1 },
  limit: 10
})

3. findOne

Busca un solo documento.

// Example
mcp.findOne({
  collection: "users",
  filter: { email: "user@example.com" }
})

4. aggregate

Ejecuta pipelines de agregación.

// Example
mcp.aggregate({
  collection: "orders",
  pipeline: [
    { $match: { status: "completed" } },
    { $group: { _id: "$userId", total: { $sum: "$amount" } } }
  ]
})

5. count

Cuenta documentos que coinciden con un filtro.

// Example
mcp.count({
  collection: "products",
  filter: { inStock: true }
})

6. distinct

Obtiene valores distintos para un campo.

// Example
mcp.distinct({
  collection: "orders",
  field: "status"
})

7. insertOne

Inserta un solo documento.

// Example
mcp.insertOne({
  collection: "users",
  document: { name: "John Doe", email: "john@example.com" }
})

8. updateOne

Actualiza un solo documento.

// Example
mcp.updateOne({
  collection: "users",
  filter: { _id: "123" },
  update: { $set: { status: "active" } }
})

9. deleteOne

Elimina un solo documento.

// Example
mcp.deleteOne({
  collection: "users",
  filter: { _id: "123" }
})

10. getSchema

Analiza la estructura de la colección y descubre los nombres de los campos.

// Example
mcp.getSchema({
  collection: "users",
  sampleSize: 100
})

// Returns:
{
  "collection": "users",
  "sampleSize": 100,
  "fields": {
    "_id": {
      "types": ["ObjectId"],
      "examples": ["507f1f77bcf86cd799439011"],
      "frequency": "100/100",
      "percentage": 100
    },
    "email": {
      "types": ["string"],
      "examples": ["user@example.com"],
      "frequency": "100/100",
      "percentage": 100
    }
  }
}

Anotaciones de herramientas (pistas MCP)

Las herramientas están anotadas con MCP ToolAnnotations para que los clientes puedan distinguir las herramientas de solo lectura de las que pueden escribir y marcar las operaciones destructivas:

HerramientareadOnlyHintidempotentHintdestructiveHintNotas
listCollectionstrue––Solo lectura
findtrue––Solo lectura
findOnetrue––Solo lectura
aggregatetrue––Solo lectura (puede ejecutar etapas de escritura)
counttrue––Solo lectura
distincttrue––Solo lectura
getSchematrue––Solo lectura
insertOnefalsefalsefalseAditiva; reintentar inserta un documento nuevo
updateOnefalsefalsetrueModifica documentos existentes; $inc/$push no son idempotentes
deleteOnefalsetruetrueEliminar un documento ya inexistente es una operación nula

Nota: aggregate está anotada como solo lectura, pero puede contener etapas de escritura (p. ej. $out, $merge): inspecciona los pipelines antes de ejecutarlos.

Buenas prácticas

  1. Usa el descubrimiento de esquemas primero: antes de consultar, ejecuta getSchema para entender los nombres de los campos
  2. Maneja ObjectIds: el servidor convierte automáticamente los IDs de cadena a ObjectIds
  3. Usa proyecciones: limita los campos devueltos para mejorar el rendimiento
  4. Operaciones por lotes: usa pipelines de agregación para consultas complejas

Ejemplos

Uso básico

// Get schema first to avoid field name mistakes
const schema = await mcp.getSchema({ collection: "reports" });

// Use correct field names from schema
const reports = await mcp.find({
  collection: "reports",
  filter: { organization_id: "64ba7374f8b63db2083b2665" },
  limit: 10
});

Agregación avanzada

const analytics = await mcp.aggregate({
  collection: "orders",
  pipeline: [
    { $match: { createdAt: { $gte: new Date("2024-01-01") } } },
    { $group: {
      _id: { $dateToString: { format: "%Y-%m", date: "$createdAt" } },
      revenue: { $sum: "$amount" },
      count: { $sum: 1 }
    }},
    { $sort: { _id: 1 } }
  ]
});

Depuración

Puedes usar el MCP Inspector para depurar el servidor, inspeccionar los esquemas de las herramientas y llamar a las herramientas de forma interactiva:

npx @modelcontextprotocol/inspector npx -y @sourabhshegane/mongodb-mcp-that-works@latest

Configura MONGODB_URI (y opcionalmente MONGODB_DATABASE) en tu entorno antes de lanzar el inspector.

Solución de problemas

Problemas de conexión

  • Verifica que tu URI de MongoDB sea correcta
  • Comprueba la conectividad de red con MongoDB Atlas
  • Asegúrate de que la lista blanca de IP incluya tu IP actual

Errores en nombres de campos

  • Usa siempre getSchema para descubrir los nombres de campos correctos
  • Recuerda que MongoDB distingue entre mayúsculas y minúsculas
  • Revisa si hay errores tipográficos en las rutas de campos anidados (p. ej., "user.profile.name")

Rendimiento

  • Usa índices para los campos consultados con frecuencia
  • Limita los conjuntos de resultados con el parámetro limit
  • Usa proyecciones para devolver solo los campos necesarios

Pruebas

El repositorio incluye un conjunto de pruebas automatizadas (node:test, sin framework adicional):

npm test

Esto primero compila y luego ejecuta:

  • Pruebas unitarias (tests/unit.test.mjs): protocolo MCP: versión negociada, los 10 esquemas de herramientas, ToolAnnotations y manejo de errores. No se requiere base de datos.
  • Pruebas de extremo a extremo (tests/e2e.test.mjs): recorrido completo de CRUD contra un MongoDB real (insertOne → find/findOne/count/distinct/aggregate → updateOne → getSchema → deleteOne), además de conversión automática de ObjectId y comprobaciones de idempotencia. Se omite automáticamente con una nota cuando no hay MongoDB accesible.

El conjunto se conecta a MongoDB en MONGODB_URI (por defecto mongodb://127.0.0.1:27017) y usa una base de datos desechable que elimina después, por lo que es seguro frente a cualquier dato existente. CI ejecuta ambos conjuntos contra un MongoDB real (Docker mongo:7) en cada push/PR.

Contribuciones

Las contribuciones son bienvenidas: nuevas herramientas, correcciones de errores, ejemplos y mejoras de documentación. Se agradecen las pull requests y los issues. Consulta CHANGELOG.md para ver el historial de versiones. Para ver ejemplos de otros servidores MCP, consulta las implementaciones de referencia.

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles

Registro de cambios

Consulta CHANGELOG.md para ver el historial completo.

VersiónnpmGitHub ReleaseDestacados
0.1.8npmv0.1.8Conjunto de pruebas automatizadas unitarias + e2e de MongoDB
0.1.7npmv0.1.7ToolAnnotations, SDK 1.30, documentación estándar del repositorio
0.1.6npmv0.1.6CI/CD, registro de cambios e insignias del repositorio
0.1.5npmv0.1.5Correcciones de metadatos y propiedad posteriores a la migración
0.1.3npmv0.1.3Publicado con documentación de instalación @latest
0.1.2npmv0.1.2URLs del repositorio actualizadas a mongodb-mcp-that-works
0.1.0npmv0.1.0Versión inicial

Lanzamientos

Todas las versiones publicadas en npm también tienen GitHub Releases etiquetadas con comprobaciones de compilación. El repositorio usa GitHub Actions para integración continua y publicación automatizada:

  • Los pushes de etiquetas (v*) activan comprobaciones de lint/compilación y, una vez que pasan, una publicación automatizada en npm
  • Cada versión publicada tiene un GitHub Release correspondiente

Hecho por necesidad, ya que el MongoDB MCP oficial no funcionó para mí