mcp-devdb

Servidor MCP de solo lectura y seguro para bases de datos de desarrollo locales. Los agentes de codificación necesitan constantemente ver tu base de datos de desarrollo (esquema, datos de muestra, planes de consulta, tamaños de tabla), pero un conector de base de datos ingenuo les otorga acceso de escritura completo. mcp-devdb es la alternativa protegida: un servidor del Protocolo de contexto de modelo que expone herramientas de introspección detrás de una protección SQL de solo lectura reforzada, enmascaramiento de columnas, límites de resultados y un presupuesto de consultas por sesión.

Backends en v1: PostgreSQL (a través de postgres) y SQLite (a través de better-sqlite3). La interfaz del adaptador es neutral respecto al motor, por lo que MySQL se puede añadir más adelante.

Inicio rápido

1. Crea mcp-devdb.json junto a donde se ejecutará el servidor (consulta mcp-devdb.example.json):

{
  "databases": {
    "app": { "url": "postgres://dev:dev@localhost:5432/app_development" },
    "cache": { "url": "sqlite:./data/cache.db" }
  }
}

2. Ejecútalo:

npx mcp-devdb --config ./mcp-devdb.json

El servidor habla MCP a través de stdio; apunta tu cliente MCP a ese comando. Las cadenas de conexión viven solo en el archivo de configuración o en variables de entorno ("url": "env:MY_DB_URL", o el respaldo MCP_DEVDB_URL sin archivo de configuración); el modelo nunca puede proporcionar una.

Claude Code

claude mcp add devdb -- npx mcp-devdb --config /absolute/path/to/mcp-devdb.json

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "devdb": {
      "command": "npx",
      "args": ["mcp-devdb", "--config", "/absolute/path/to/mcp-devdb.json"]
    }
  }
}

Related MCP server: MCP PostgreSQL

Herramientas

database es opcional cuando hay exactamente una base de datos configurada; con varias, indica cuál quieres.

Configuración

mcp-devdb.json en el directorio de trabajo, o cualquier ruta mediante --config:

{
  "databases": {
    "app": {
      "url": "postgres://dev:dev@localhost:5432/app_development",
      "allowTables": ["users", "orders", "public.events_*"],
      "denyTables": ["audit_log"]
    },
    "billing": { "url": "env:BILLING_DEV_DATABASE_URL" }
  },
  "maskPatterns": ["password", "secret", "token", "key", "hash", "ssn", "card"],
  "queryBudget": 100,
  "rowLimit": 200,
  "byteLimit": 262144,
  "statementTimeoutMs": 5000
}

• allowTables / denyTables: nombres que no distinguen entre mayúsculas y minúsculas con comodines *; las reglas que contienen un punto coinciden con esquema.tabla. Denegar tiene prioridad; una lista de permitidos no vacía es excluyente.

• maskPatterns: expresiones regulares que no distinguen entre mayúsculas y minúsculas que se comparan con los nombres de columna.

• Banderas de CLI: --config <ruta>, --no-mask (deshabilitar el enmascaramiento de columnas), --help, --version.

Modelo de seguridad (resumen)

El modelo de amenazas completo se encuentra en SECURITY.md. En resumen:

• Protección de solo lectura: cada declaración de run_query/explain_query se tokeniza (comillas, escapes E'...', comentarios, cadenas entre comillas con $) y debe comenzar con SELECT / WITH / EXPLAIN / SHOW / VALUES; la entrada de múltiples declaraciones y las palabras clave de escritura/DDL en cualquier lugar del nivel superior se rechazan: se detecta un CTE seguido de INSERT, SELECT 'DROP TABLE x' no es un falso positivo.

• Aplicación a nivel de motor: los archivos SQLite se abren de solo lectura; las sesiones de PostgreSQL se ejecutan con default_transaction_read_only=on, transacciones explícitas BEGIN READ ONLY y tiempos de espera de declaración.

• Enmascaramiento de columnas activado de forma predeterminada (--no-mask para desactivarlo), límites de resultados y un presupuesto de consultas por sesión (predeterminado: 100; el agotamiento te indica que reinicies el servidor).

• Las credenciales nunca llegan al modelo: las cadenas de conexión provienen solo de la configuración local o variables de entorno y se eliminan de todos los mensajes de error.

Prueba de humo

scripts/verify-stdio.mjs crea una base de datos SQLite temporal, inicia node dist/cli.js y maneja un protocolo de enlace MCP real a través de stdio con JSON-RPC sin procesar. Salida real:

$ node scripts/verify-stdio.mjs
initialize -> mcp-devdb 0.1.0 (protocol 2025-06-18)
tools/list -> db_overview, describe_table, explain_query, list_tables, run_query, sample_rows
tools/call list_tables ->
{
  "database": "demo",
  "dialect": "sqlite",
  "tableCount": 2,
  "tables": [
    {
      "schema": null,
      "name": "orders",
      "type": "table",
      "rowEstimate": 3,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    },
    {
      "schema": null,
      "name": "users",
      "type": "table",
      "rowEstimate": 2,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    }
  ]
}
tools/call run_query "DROP TABLE users" -> isError=true
  Query rejected by read-only guard: Only read-only statements are allowed; the statement must start with one of: SELECT, WITH, EXPLAIN, SHOW, VALUES
SMOKE TEST PASSED

Limitaciones

• Aún no hay MySQL. La interfaz DbAdapter en src/adapters/types.ts es el punto de extensión.

• Solo bases de datos de desarrollo. La protección bloquea las escrituras a nivel de SQL, pero un SELECT aún puede invocar funciones mal etiquetadas o de extensiones con efectos secundarios (por ejemplo, dblink abriendo su propia conexión que no es de solo lectura). Aceptado para bases de datos de desarrollo; nunca lo apuntes a producción. Consulta SECURITY.md.

• La protección es conservadora: las columnas sin comillas con nombres de palabras clave prohibidas (por ejemplo, una columna llamada literalmente update) se rechazan; ponlas entre comillas ("update") para continuar.

• SELECT ... FOR UPDATE se rechaza (bloquea filas).

• Los recuentos de filas de SQLite usan COUNT(*); en archivos enormes, list_tables puede ser lento.

Desarrollo

npm install
npm run lint && npm run typecheck && npm test && npm run build
node scripts/verify-stdio.mjs

Licencia

MIT — Copyright (c) 2026 Aminyx