Servidor MCP MongoDB para LLMS

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los LLM interactuar directamente con las bases de datos MongoDB. Consulta colecciones, inspecciona esquemas y gestiona datos sin problemas mediante 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 (por ejemplo, Claude Desktop, Cursor.ai)
• Servidores MCP : servicios que exponen datos y funcionalidades (como este servidor MongoDB)

Beneficios clave del 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 forma consistente.
• Ecosistema sostenible : promueve conectores reutilizables que funcionan entre múltiples clientes LLM

✨ Características

• 🔍 Inspección del esquema de colección
• 📊 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úrese de tener:

• Node.js (v18 o superior)
• Instancia de MongoDB (local o remota)
• Un cliente MCP como Claude Desktop o Cursor.ai

Puede verificar su instalación de Node.js ejecutando:

🚀 Inicio rápido

Para comenzar, busque la URL de conexión de MongoDB y agregue esta configuración a su archivo de configuración de Claude Desktop:

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

Instalación mediante herrería

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

Integración de Cursor.ai

Para utilizar MongoDB MCP con Cursor.ai:

1. Abra Cursor.ai y navegue a Configuración > Funciones
2. Busque "Servidores MCP" en el panel de características
3. Agregue 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: Actualmente, el cursor solo admite herramientas MCP en la función Agente en Composer.

Configuración de la zona de pruebas

Si no tiene un servidor MongoDB al cual conectarse y desea crear un espacio aislado de muestra, siga estos pasos:

1. Inicie MongoDB usando Docker Compose:

2. Sembrar la base de datos con datos de prueba:

Configurar Claude Desktop

Agregue esta configuración a su archivo de configuración de Claude Desktop:

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

Modo de desarrollo local:

Estructura de datos de la zona de pruebas

El script de semilla crea tres colecciones con datos de muestra:

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 precios e inventario
• Etiquetas y valoraciones

Pedidos

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

🎯 Ejemplos de indicaciones

Pruebe estas indicaciones con Claude para explorar la funcionalidad:

Operaciones básicas

Consultas avanzadas

Gestión de índices

Operaciones de documentos

📝 Herramientas disponibles

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

Herramientas de consulta

• listCollections : enumera 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 índice

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

🛠️ Desarrollo

Este proyecto está construido con:

• TypeScript para desarrollo con seguridad de tipos
• Controlador Node.js de MongoDB para operaciones de bases de datos
• Zod para la validación de esquemas
• SDK de protocolo de contexto de modelo para implementación de servidor

Para configurar el entorno de desarrollo:

Consideraciones de seguridad

Al utilizar este servidor MCP con su base de datos MongoDB:

1. Cree un usuario MongoDB dedicado con los permisos mínimos necesarios para su caso de uso
2. Nunca utilice credenciales de administrador en entornos de producción
3. Habilitar el registro de acceso para fines de auditoría
4. Establecer permisos de lectura y escritura adecuados en las colecciones
5. Utilice parámetros de cadena de conexión para restringir el acceso (por ejemplo, readPreference=secondary )
6. Considere la posibilidad de incluir direcciones IP permitidas para restringir el acceso a la base de datos

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

🌐 Cómo funciona

El servidor MCP de MongoDB:

1. Se conecta a su base de datos MongoDB utilizando la cadena de conexión proporcionada
2. Expone las operaciones de MongoDB como herramientas que siguen la especificación MCP
3. Valida entradas usando Zod para seguridad de tipos.
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 la validación adecuada para evitar problemas de seguridad como ataques de inyección.

📦 Implementación

Puede implementar este servidor MCP de varias maneras:

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

❓ Solución de problemas

Problemas comunes

1. Errores de conexión
   • Verifique que su cadena de conexión de MongoDB sea correcta
   • Compruebe que su servidor MongoDB esté en funcionamiento y sea accesible
   • Asegúrese de que los permisos de red permitan la conexión
2. Problemas de autenticación
   • Confirme que el nombre de usuario y la contraseña son correctos
   • Verifique que la base de datos de autenticación esté especificada (normalmente authSource=admin )
   • Compruebe si MongoDB requiere conexiones TLS/SSL
3. Problemas de ejecución de herramientas
   • Reinicie Claude Desktop o Cursor.ai por completo
   • Consulte los registros para ver mensajes de error detallados:
     # macOS tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
4. Problemas de rendimiento
   • Considere agregar índices apropiados a los campos consultados con frecuencia
   • Utilice la proyección para limitar los datos devueltos en las consultas
   • Utilice los parámetros de límite y omisión para la paginación

Obtener ayuda

Si encuentra problemas:

• Revisar la documentación del MCP
• Envíe un problema en nuestro repositorio de GitHub

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

1. Bifurcar el repositorio
2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )
4. Empujar a la rama ( git push origin feature/amazing-feature )
5. Abrir una solicitud de extracción

📜 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.