MongoDB

Interactúa con bases de datos MongoDB usando lenguaje natural. Consulta colecciones, inspecciona esquemas y administra datos.

GitHub
15
Prueba este MCPPatrocinado

Documentación

🗄️ Servidor MCP de MongoDB para LLMS

Node.js 18+ License: MIT npm version smithery badge

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los LLM interactuar directamente con bases de datos MongoDB. Consulta colecciones, inspecciona esquemas y gestiona datos sin problemas a través del lenguaje natural.

📚 ¿Qué es el Protocolo de Contexto de Modelo (MCP)?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto desarrollado por Anthropic que crea una forma universal para que los sistemas de IA se conecten con fuentes de datos y herramientas externas. MCP establece un canal de comunicación estandarizado entre:

  • Clientes MCP: Asistentes de IA como Claude que consumen datos (p. ej., Claude Desktop, Cursor.ai)
  • Servidores MCP: Servicios que exponen datos y funcionalidad (como este servidor de MongoDB)

Beneficios clave de MCP:

  • Acceso Universal: Proporciona un protocolo único para que los asistentes de IA consulten datos de diversas fuentes
  • Conexiones Estandarizadas: Gestiona la autenticación, las políticas de uso y los formatos de datos de manera consistente
  • Ecosistema Sostenible: Promueve conectores reutilizables que funcionan en múltiples clientes LLM

✨ Características

  • 🔍 Inspección de esquemas de colecciones
  • 📊 Consulta y filtrado de documentos
  • 📈 Gestión de índices
  • 📝 Operaciones con documentos (insertar, actualizar, eliminar)
  • 🔒 Acceso seguro a la base de datos mediante cadenas de conexión
  • 📋 Manejo integral de errores y validación

📋 Requisitos previos

Antes de comenzar, asegúrate de tener:

Puedes verificar tu instalación de Node.js ejecutando:

node --version  # Should show v18.0.0 or higher

🚀 Inicio rápido

Para comenzar, encuentra tu URL de conexión de MongoDB y añade esta configuración al archivo de 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": [
        "mongo-mcp",
        "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin"
      ]
    }
  }
}

Instalación mediante Smithery

Smithery.ai es una plataforma de registro para servidores MCP que simplifica el descubrimiento y la instalación. Para instalar el Servidor MCP de MongoDB para Claude Desktop automáticamente mediante Smithery:

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

Integración con Cursor.ai

Para usar MongoDB MCP con Cursor.ai:

  1. Abre Cursor.ai y navega a Configuración > Funciones
  2. Busca "Servidores MCP" en el panel de funciones
  3. Añade un nuevo servidor MCP con la siguiente configuración:
    • Nombre: mongodb
    • Comando: npx
    • Argumentos: mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin

Nota: Cursor actualmente admite herramientas MCP solo en la función Agent en Composer.

Configuración del entorno de pruebas

Si no tienes un servidor MongoDB al que conectarte y deseas crear un entorno de pruebas de muestra, sigue estos pasos:

  1. Inicia MongoDB usando Docker Compose:
docker-compose up -d
  1. Rellena la base de datos con datos de prueba:
npm run seed

Configurar Claude Desktop

Añade esta configuración al archivo de configuración de Claude Desktop:

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

Modo de desarrollo local:

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": [
        "dist/index.js",
        "mongodb://root:example@localhost:27017/test?authSource=admin"
      ]
    }
  }
}

Estructura de datos del entorno de pruebas

El script de inicialización crea tres colecciones con datos de ejemplo:

Usuarios

  • Información personal (nombre, correo electrónico, edad)
  • Dirección anidada con coordenadas
  • Matrices de intereses
  • Fechas de membresía

Productos

  • Detalles del producto (nombre, SKU, categoría)
  • Especificaciones anidadas
  • Información de precio e inventario
  • Etiquetas y valoraciones

Pedidos

  • Detalles del pedido con artículos
  • Referencias de usuario
  • Información de envío y pago
  • Seguimiento de estado

🎯 Ejemplos de indicaciones

Prueba estas indicaciones con Claude para explorar la funcionalidad:

Operaciones básicas

"What collections are available in the database?"
"Show me the schema for the users collection"
"Find all users in San Francisco"

Consultas avanzadas

"Find all electronics products that are in stock and cost less than $1000"
"Show me all orders from the user john@example.com"
"List the products with ratings above 4.5"

Gestión de índices

"What indexes exist on the users collection?"
"Create an index on the products collection for the 'category' field"
"List all indexes across all collections"

Operaciones con documentos

"Insert a new product with name 'Gaming Laptop' in the products collection"
"Update the status of order with ID X to 'shipped'"
"Find and delete all products that are out of stock"

📝 Herramientas disponibles

El servidor proporciona estas herramientas para la interacción con la base de datos:

Herramientas de consulta

  • listCollections: Lista las colecciones disponibles en la base de datos
  • find: Consulta documentos con filtrado y proyección
  • insertOne: Inserta un solo documento en una colección
  • updateOne: Actualiza un solo documento en una colección
  • deleteOne: Elimina un solo documento de una colección

Herramientas de índices

  • createIndex: Crea un nuevo índice en una colección
  • dropIndex: Elimina un índice de una colección
  • indexes: Lista los índices de una colección

🛠️ Desarrollo

Este proyecto está construido con:

  • TypeScript para un desarrollo con seguridad de tipos
  • Controlador de Node.js de MongoDB para operaciones de base de datos
  • Zod para la validación de esquemas
  • SDK del Protocolo de Contexto de Modelo para la implementación del servidor

Para configurar el entorno de desarrollo:

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

🔒 Consideraciones de seguridad

Al usar este servidor MCP con tu base de datos MongoDB:

  1. Crea un usuario de MongoDB dedicado con los permisos mínimos necesarios para tu caso de uso
  2. Nunca uses credenciales de administrador en entornos de producción
  3. Habilita el registro de acceso con fines de auditoría
  4. Establece permisos de lectura/escritura adecuados en las colecciones
  5. Usa parámetros de la cadena de conexión para restringir el acceso (p. ej., readPreference=secondary)
  6. Considera la lista de permitidos de IP para restringir el acceso a la base de datos

⚠️ IMPORTANTE: Sigue siempre el principio de privilegio mínimo al configurar el acceso a la base de datos.

🌐 Cómo funciona

El servidor MCP de MongoDB:

  1. Se conecta a tu base de datos MongoDB usando la cadena de conexión proporcionada
  2. Expone las operaciones de MongoDB como herramientas que siguen la especificación MCP
  3. Valida las entradas usando Zod para la seguridad de tipos y la protección
  4. Ejecuta consultas y devuelve datos estructurados al cliente LLM
  5. Gestiona la agrupación de conexiones y el manejo adecuado de errores

Todas las operaciones se ejecutan con una validación adecuada para prevenir problemas de seguridad como ataques de inyección.

📦 Implementación

Puedes implementar este servidor MCP de varias maneras:

  • Localmente mediante npx (como se muestra en el Inicio rápido)
  • Como paquete npm global: npm install -g @coderay/mongo-mcp-server
  • En un contenedor Docker (consulta el Dockerfile en el repositorio)
  • Como servicio en plataformas como Heroku, Vercel o AWS

❓ Solución de problemas

Problemas comunes

  1. Errores de conexión

    • Verifica que tu cadena de conexión de MongoDB sea correcta
    • Comprueba que tu servidor MongoDB esté en ejecución y sea accesible
    • Asegúrate de que los permisos de red permitan la conexión

  2. Problemas de autenticación

    • Confirma que el nombre de usuario y la contraseña sean correctos
    • Verifica que la base de datos de autenticación esté especificada (generalmente authSource=admin)
    • Comprueba si MongoDB requiere conexiones TLS/SSL

  3. Problemas de ejecución de herramientas

    • Reinicia Claude Desktop o Cursor.ai por completo
    • Revisa los registros para ver mensajes de error detallados: 
      # macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

  4. Problemas de rendimiento

    • Considera añadir índices apropiados a los campos consultados con frecuencia
    • Usa la proyección para limitar los datos devueltos en las consultas
    • Usa los parámetros de límite y omisión para la paginación

Obtener ayuda

Si encuentras problemas:

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de extracción.

  1. Haz un fork del repositorio
  2. Crea tu rama de funcionalidad (git checkout -b feature/amazing-feature)
  3. Realiza tus confirmaciones de cambios (git commit -m 'Add some amazing feature')
  4. Envía los cambios a la rama (git push origin feature/amazing-feature)
  5. Abre una Solicitud de extracción

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENCIA para más detalles.