MongoDB Read-Only MCP

Servidor MCP en Node.js/TypeScript para consultar una o varias conexiones MongoDB desde OpenCode sin exponer herramientas de escritura.

Capacidades

• Lista conexiones configuradas sin mostrar credenciales.
• Lista bases de datos y colecciones.
• Ejecuta find, count, distinct y pipelines aggregate en modo lectura.
• Busca un valor en varias colecciones de una base cuando no sabes dónde está la información.
• Bloquea etapas de agregación de escritura o administración como $out, $merge, $currentOp y $listSessions.
• Limita resultados y tiempo de consulta para evitar respuestas enormes o consultas colgadas.

Requisitos

• Node.js 20 o superior.
• Acceso de red a MongoDB.
• Un usuario MongoDB idealmente con permisos de solo lectura (read o readAnyDatabase).

Uso con NPX

Una vez publicado en npm, se puede consumir sin clonar el repositorio:

npx -y @munlib/mongodb-readonly-mcp

Instalación Para Desarrollo

npm install
npm run build

Configuración Segura

No guardes credenciales reales en el repositorio. Usa variables de entorno desde OpenCode, tu terminal o un gestor de secretos.

Una Conexión

$env:MONGO_NAME = "mongoKubernet"
$env:MONGO_URI = "mongodb://usuario:[email protected]:27017/admin?authSource=admin"
npm start

Varias Conexiones

$env:MONGO_CONNECTIONS = '[{"name":"mongoKubernet","uri":"mongodb://usuario:[email protected]:27017/admin?authSource=admin"},{"name":"local","uri":"mongodb://localhost:27017/admin"}]'
npm start

También puedes usar una URL larga como la de Studio 3T siempre que sea una URI MongoDB válida:

mongodb://admin:[email protected]:27017/admin?retryWrites=true&loadBalanced=false&serverSelectionTimeoutMS=5000&connectTimeoutMS=10000&authSource=admin&authMechanism=SCRAM-SHA-1

Variables Disponibles

| Variable | Descripción | Default | | --- | --- | --- | | MONGO_CONNECTIONS | JSON con múltiples conexiones: [{"name":"...","uri":"..."}]. | - | | MONGO_URI | URI de una sola conexión. | - | | MONGO_NAME | Nombre lógico para MONGO_URI. | default | | MONGO_DEFAULT_LIMIT | Límite por defecto de documentos devueltos. | 25 | | MONGO_MAX_LIMIT | Límite máximo permitido. | 100 | | MONGO_QUERY_TIMEOUT_MS | Timeout por consulta. | 15000 | | MONGO_SEARCH_COLLECTION_LIMIT | Máximo de colecciones escaneadas por búsqueda global. | 50 | | MONGO_SEARCH_FIELDS_LIMIT | Máximo de campos detectados por colección para búsqueda global. | 30 |

Configuración en OpenCode

Agrega un MCP local en tu opencode.json o opencode.jsonc. El campo command debe ser un arreglo.

Usando NPM

Esta es la forma recomendada para otros equipos o máquinas:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mongodb-readonly": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "@munlib/mongodb-readonly-mcp"],
      "env": {
        "MONGO_CONNECTIONS": "[{\"name\":\"mongoKubernet\",\"uri\":\"mongodb://usuario:[email protected]:27017/admin?authSource=admin\"}]",
        "MONGO_DEFAULT_LIMIT": "25",
        "MONGO_MAX_LIMIT": "100",
        "MONGO_QUERY_TIMEOUT_MS": "15000",
        "MONGO_SEARCH_COLLECTION_LIMIT": "50",
        "MONGO_SEARCH_FIELDS_LIMIT": "30"
      }
    }
  }
}

Después de cambiar opencode.json, reinicia OpenCode para que cargue el MCP.

Usando Build Local

Para desarrollo local también puedes apuntar al archivo compilado:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mongodb-readonly": {
      "type": "local",
      "enabled": true,
      "command": ["node", "C:/ruta/al/proyecto/dist/index.js"],
      "env": {
        "MONGO_CONNECTIONS": "[{\"name\":\"mongoKubernet\",\"uri\":\"mongodb://usuario:[email protected]:27017/admin?authSource=admin\"}]"
      }
    }
  }
}

Herramientas MCP

| Herramienta | Uso | | --- | --- | | mongo_list_connections | Ver nombres de conexiones configuradas. | | mongo_list_databases | Ver bases disponibles en una conexión. | | mongo_list_collections | Ver colecciones de una base. | | mongo_find_documents | Consultar documentos con filtro, proyección, orden, límite y skip. | | mongo_count_documents | Contar documentos por filtro. | | mongo_distinct_values | Obtener valores distintos de un campo. | | mongo_aggregate_readonly | Ejecutar agregaciones de lectura. | | mongo_search_database | Buscar un valor en varias colecciones de una base. |

Ejemplos de Preguntas en OpenCode

• "Lista las bases de datos disponibles en mongoKubernet."
• "En la base apiLogs, lista las colecciones."
• "Busca el id 64f... en toda la base backoffice."
• "En ecommerce_mercados_prod.orders, encuentra documentos donde customer.email sea [email protected]."
• "Cuenta documentos en logs.requests para el endpoint /api/login."

Garantías y Límites de Solo Lectura

Este MCP no expone operaciones insert, update, delete, drop, create, renameCollection ni comandos arbitrarios. Para agregaciones, bloquea etapas conocidas que escriben o exponen información administrativa.

La recomendación fuerte es usar además un usuario MongoDB con permisos de solo lectura. La seguridad real debe aplicarse en la base de datos, no solo en el MCP.

Publicación en NPM

El paquete está preparado para publicarse como:

@munlib/mongodb-readonly-mcp

Antes de publicar, verifica que no existan credenciales en archivos versionados. Los scripts ejecutan build, typecheck, npm pack --dry-run y piden confirmación antes de publicar.

Windows PowerShell

Modo guiado:

npm run publish:npm

Solo validar sin publicar:

npm run publish:dry-run

Publicar una actualización patch:

pwsh -File scripts/publish-npm.ps1 -Bump patch

Si npm exige 2FA al publicar, el script pedirá el código OTP. También puedes pasarlo directamente:

pwsh -File scripts/publish-npm.ps1 -Bump none -Otp 123456

También puedes publicar usando un Access Token de npm sin guardar credenciales en el proyecto:

$env:NPM_TOKEN = "npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
pwsh -File scripts/publish-npm.ps1 -Bump none

Linux o macOS

Modo guiado:

npm run publish:npm:bash

En el modo guiado puedes escribir el número de la opción o el nombre directamente, por ejemplo 1, none, patch, minor, major o prerelease.

Solo validar sin publicar:

npm run publish:npm:bash -- --dry-run

Solo validar sin publicar y sin pedir login:

npm run publish:npm:bash -- --bump none --dry-run --skip-login

Primera publicación sin cambiar la versión:

npm run publish:npm:bash -- --bump none

Publicar una actualización patch:

npm run publish:npm:bash -- --bump patch

Si npm exige 2FA al publicar, el script pedirá el código OTP. También puedes pasarlo directamente:

npm run publish:npm:bash -- --bump none --otp 123456

También puedes publicar usando un Access Token de npm sin guardar credenciales en el proyecto:

export NPM_TOKEN="npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
npm run publish:npm:bash -- --bump none

Comprobación Manual Rápida

Si solo quieres revisar el paquete sin iniciar sesión ni publicar:

npm run publish:check

Login y Credenciales

Los scripts no guardan credenciales. Si no hay sesión activa, ejecutan:

npm login

npm login pedirá usuario, contraseña y 2FA si tu cuenta lo tiene activado, o abrirá el navegador según la configuración actual de npm.

Si al publicar aparece E403 Two-factor authentication or granular access token with bypass 2fa enabled is required, significa que npm requiere un código 2FA para esa publicación. Vuelve a ejecutar el script y escribe el código OTP actual de tu app autenticadora cuando lo solicite.

También puedes usar un token granular de npm con permiso de publicación y bypass 2FA habilitado, pero para uso manual es más simple usar el OTP.

Publicar con Access Token de NPM

Sí se puede publicar directamente con un Access Token. Es la opción recomendada si tu cuenta u organización exige 2FA y el OTP manual falla.

En npm crea un token desde Access Tokens. Para publicar paquetes necesitas un token con permisos de publicación sobre @munlib/mongodb-readonly-mcp o sobre la organización munlib.

Recomendaciones para el token:

• Usa un token granular si npm te da esa opción.
• Dale permiso de lectura/escritura solo al paquete u organización necesaria.
• Habilita bypass 2FA si npm lo solicita para publicaciones automatizadas.
• No pegues el token en README.md, .env, opencode.jsonc ni commits.
• Si se filtra, revócalo inmediatamente desde npm.

Los scripts leen el token desde NPM_TOKEN, crean un .npmrc temporal fuera del proyecto, publican con ese archivo y lo eliminan al terminar.

Windows PowerShell:

$env:NPM_TOKEN = "npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
npm run publish:npm

Linux o macOS:

export NPM_TOKEN="npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
npm run publish:npm:bash -- --bump none

Para probar sin publicar:

export NPM_TOKEN="npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
npm run publish:npm:bash -- --bump none --dry-run

Si no quieres dejar el token en la sesión después de publicar, elimínalo:

Remove-Item Env:NPM_TOKEN

unset NPM_TOKEN

Versiones

Para primera publicación, selecciona none cuando el script pregunte el tipo de publicación.

Para actualizaciones, usa:

patch      # 0.1.0 -> 0.1.1
minor      # 0.1.0 -> 0.2.0
major      # 0.1.0 -> 1.0.0
prerelease # 0.1.0 -> 0.1.1-0

Los scripts usan npm version --no-git-tag-version, por lo que actualizan package.json y package-lock.json, pero no crean commits ni tags automáticamente.