MongoDB MCP Server

Un servidor MCP que proporciona herramientas y prompts para interactuar con una base de datos MongoDB.

Documentación

Servidor MCP de MongoDB

Un servidor robusto de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas y avisos para interactuar con una base de datos MongoDB. Construido con Node.js y MongoDB, con manejo elegante de apagado y gestión integral de errores.

Características

Integración con MongoDB usando Mongoose
Herramientas de gestión de usuarios:
- create-user: Crear un nuevo usuario
- get-user: Recuperar usuario por correo electrónico
- list-users: Listar todos los usuarios con paginación
Avisos interactivos para operaciones guiadas
Manejo elegante de apagado
Gestión integral de errores
Implementación limpia en un solo archivo

Requisitos previos

Node.js (última versión LTS)
MongoDB (v8.0 o superior)
Claude para escritorio (última versión)
Visual Studio Code con la extensión Cursor (para desarrollo)

Configuración de desarrollo

Instalar MongoDB:

# Using Homebrew on macOS
brew tap mongodb/brew
brew install mongodb-community

# Start MongoDB service
brew services start mongodb-community

Instalar Cursor en VS Code:
- Abrir VS Code
- Ir a Extensiones (Ctrl+Shift+X)
- Buscar "Cursor"
- Hacer clic en Instalar

Clonar y configurar:

git clone <repository-url>
cd learn-mcp-mongo
npm install

Configurar el entorno:

cp .env.example .env
# Edit .env with your MongoDB URI if different from default

Inicio rápido

Clonar o descargar este repositorio
Instalar dependencias:
```
npm install
```
Configurar MongoDB:
- Asegurarse de que MongoDB esté ejecutándose localmente (predeterminado: mongodb://localhost:27017)
- O actualizar el archivo .env con su cadena de conexión de MongoDB:
```
MONGODB_URI=your_mongodb_connection_string
```
Configurar Claude para escritorio:
- Abrir o crear ~/Library/Application Support/Claude/claude_desktop_config.json
- Agregar la siguiente configuración:
```
{
  "mcpServers": {
    "mcp-mongo": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"]
    }
  }
}
```
Iniciar Claude para escritorio
- El servidor MCP se iniciará automáticamente
- Busque el ícono "Buscar y herramientas" para acceder a las herramientas

Usar Cursor con el servidor MCP

Instalar Cursor (editor de código con IA):
- Descargar desde https://www.cursor.so/
- Instalar y abrir Cursor en su máquina
Agregar el servidor MCP a Cursor:
- Abrir Cursor
- Ir a Settings > Integrations > MCP Servers
- Hacer clic en Add MCP Server
- Completar:
  - Nombre: mcp-mongo
  - Comando: node
  - Argumentos: /absolute/path/to/server.js
  - Directorio de trabajo: /absolute/path/to/learn-mcp-mongo
- Guardar y habilitar la integración
Usar las funciones de IA de Cursor:
- Abrir su carpeta de proyecto en Cursor
- Usar /help en la paleta de comandos para ver los comandos de IA disponibles
- Usar /edit, /fix, /doc y otras funciones de IA para interactuar con su código y las herramientas MCP
- Ahora puede probar, depurar y desarrollar su servidor MCP directamente en Cursor con asistencia de IA

Ejemplos de uso

Crear un usuario

Create a new user with:
- name: "John Doe"
- email: "john@example.com"
- age: 30

Buscar un usuario

Get user information for email: john@example.com

Estructura del proyecto

learn-mcp-mongo/
├── server.js     # Main server file with all functionality
├── .env          # Environment variables
└── package.json  # Project dependencies and scripts

Herramientas disponibles

create-user

Crea un nuevo usuario en la base de datos.

Parámetros:
- name: Nombre completo del usuario (cadena, obligatorio)
- email: Dirección de correo electrónico del usuario (cadena, obligatorio, única)
- age: Edad del usuario (número, obligatorio)

Respuesta:

{
  "_id": "user_id",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "createdAt": "2025-06-26T00:00:00.000Z"
}

get-user

Recupera un usuario por su dirección de correo electrónico.

Parámetros:
- email: Dirección de correo electrónico del usuario (cadena, obligatorio)

Respuesta:

{
  "_id": "user_id",
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "createdAt": "2025-06-26T00:00:00.000Z"
}

list-users

Lista todos los usuarios en la base de datos con paginación.

Parámetros:
- limit: Número máximo de usuarios a devolver (número, opcional, predeterminado: 10)

Respuesta:

[
  {
    "_id": "user_id",
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "createdAt": "2025-06-26T00:00:00.000Z"
  },
  // ... more users
]

Avisos disponibles

create-new-user

Un aviso interactivo que lo guía a través del proceso de creación de un nuevo usuario solicitando:

Nombre completo
Dirección de correo electrónico
Edad

Guía de desarrollo

Ejecutar el servidor

Iniciar en modo de desarrollo:

# Run with inspector for debugging
npx @modelcontextprotocol/inspector node mcp-server.js

# Or run directly
npm start

Usar Cursor en VS Code:
- Abrir el proyecto en VS Code
- Usar las funciones de IA de Cursor:
  - Escribir /help para comandos de Cursor
  - Usar /edit para sugerencias de código
  - Usar /doc para generar documentación
  - Usar /fix para obtener correcciones de errores

Depuración

Verificar los registros del servidor:

# Watch server logs in real-time
tail -f ~/Library/Logs/Claude/mcp*.log

Operaciones de MongoDB:

# Check MongoDB status
mongosh
use mcp-mongo
db.users.find()  # List all users

Probar herramientas manualmente:

# Using curl to test tools (when running in HTTP mode)
curl -X POST http://localhost:3000/tools/list-users

Características del servidor

Apagado elegante:
- Maneja señales SIGINT, SIGTERM, SIGHUP
- Cierra las conexiones de MongoDB correctamente
- Registra el proceso de apagado
Manejo de errores:
- Errores de conexión de MongoDB
- Errores de ejecución de herramientas
- Excepciones no capturadas
- Rechazos no manejados
Opciones de rendimiento:
- Tiempo de espera de conexión de MongoDB: 5s
- Frecuencia de latido: 2s
- Paginación de listado de usuarios

Solución de problemas

Asegúrese de que MongoDB esté ejecutándose y sea accesible
Verifique los registros de Claude para escritorio en ~/Library/Logs/Claude/mcp*.log
Verifique que la ruta de server.js en claude_desktop_config.json sea correcta
Reinicie Claude para escritorio después de los cambios de configuración