mcp-mongodb

Servidor MCP (Model Context Protocol) para conectar Claude a MongoDB. Con este servidor, Claude puede explorar, consultar y modificar su base de datos MongoDB directamente a través de la conversación.

Características / Herramientas

Related MCP server: Mongo-MCP

Requisitos

• Node.js ≥ 18 (desarrollado y probado en v22)

• Servidor MongoDB (local o MongoDB Atlas)

Instalación

cd d:\mcp_server\mcp_mongodb
npm install

Configuración de variables de entorno

Ejemplo de URI de Atlas:

mongodb+srv://user:password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority

Conexión con Claude Desktop

1. Abra el archivo de configuración:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json (normalmente C:\Users\<NamaAnda>\AppData\Roaming\Claude\claude_desktop_config.json)

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Añada la siguiente entrada (ajuste la ruta y las credenciales):

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": ["d:\\mcp_server\\mcp_mongodb\\index.js"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017",
        "MONGODB_DB": "nama_database_anda"
      }
    }
  }
}

3. Guarde el archivo y reinicie Claude Desktop (ciérrelo por completo y ábralo de nuevo).

4. El icono de martillo/barra de herramientas del cuadro de chat mostrará las herramientas de mcp-mongodb.

Ejemplos de uso en Claude

• "Muestra todas las bases de datos de MongoDB" → list_databases

• "¿Qué colecciones hay en la base de datos de la tienda?" → list_collections

• "Busca los 10 productos más vendidos, ordenados de mayor a menor ventas" → find con sort + limit

• "Añade un producto nuevo llamado 'Kopi Arabika' con precio 85000" → insert_one

• "Aumenta el stock de todos los productos de la categoría 'bebidas' en 10" → update_many

• "¿Cuál es el total de ventas por mes?" → aggregate con $group

• "Crea un índice único en el campo email de la colección users" → create_index

Pruebas

Prueba de humo del protocolo (no necesita MongoDB en ejecución):

npm test

Salida esperada:

PASS: initialize — server=mcp-mongodb v1.0.0
PASS: tools/list — 25 tool terdaftar
PASS: tool inti tersedia — semua ada
PASS: tools/call merespons

La llamada a server_info en la prueba de humo mostrará un mensaje de error si MongoDB no está en ejecución; eso es normal y precisamente demuestra que la ruta RPC funciona.

Seguridad y notas importantes

• Use una cuenta de MongoDB con los permisos mínimos necesarios. Si solo quiere que Claude lea datos, cree un usuario de solo lectura en MongoDB/Atlas.

• No guarde contraseñas en archivos que se suban a git. Para producción, considere almacenar MONGODB_URI en el entorno del sistema, no en el JSON de configuración.

• Las operaciones destructivas están protegidas: drop_database y delete_many con un filtro vacío exigen confirmación explícita (confirm: true), pero update_many / delete_many con un filtro concreto se ejecutan directamente; revise siempre el plan de acción de Claude antes de aprobarlo.

• La salida de las consultas está limitada (50 documentos por defecto, máximo 1000) para no exceder el contexto de Claude.

Solución de problemas

Estructura del proyecto

mcp_mongodb/
├── index.js           # Entry point: McpServer + StdioServerTransport
├── lib/
│   ├── connection.js  # Singleton MongoClient (lazy connect), env config
│   ├── helpers.js     # Result builder, parser JSON, util ObjectId
│   └── schemas.js     # Skema Zod bersama
├── tools/
│   ├── admin.js       # Info server, database, koleksi
│   ├── query.js       # Pembacaan data & agregasi
│   ├── documents.js   # Insert/update/replace/delete
│   └── indexes.js     # Manajemen index
└── test-smoke.js      # Smoke test JSON-RPC via stdio