database-mcp

Servidor MCP de base de datos SQL con paginación real de resultados en el lado del servidor — la característica que ningún servidor MCP de base de datos establecido tiene (DBHub limita filas, Google's MCP Toolbox devuelve todo, mcp-alchemy trunca a 4000 caracteres).

Implementación de referencia en PostgreSQL.

Por qué

Cada servidor MCP SQL existente o trunca resultados grandes o los vuelca completos en el contexto del modelo. La especificación MCP solo pagina operaciones de lista (tools/list), no resultados de herramientas. database-mcp cierra esa brecha:

• Una consulta se ejecuta una vez como un cursor del lado del servidor de PostgreSQL (DECLARE/FETCH FORWARD) dentro de una transacción mantenida.

• Cada fetch(cursor) continúa exactamente donde terminó la última página — sin re-ejecución, sin re-escaneo de OFFSET, y la instantánea MVCC mantiene el resultado estable incluso bajo escrituras concurrentes.

• Las páginas están limitadas por filas (page_size) y por bytes renderizados (max_page_bytes); las celdas sobredimensionadas se truncan con un marcador explícito.

• Los cursores mantenidos están limitados: máximo N concurrentes (evicción LRU), evicción por inactividad TTL, además de idle_in_transaction_session_timeout como respaldo del lado del servidor. Los cursores agotados se cierran automáticamente.

Related MCP server: pgsql-mcp

Perfiles de conexión — gestionados por la IA en tiempo de ejecución

Las conexiones son perfiles con nombre, persistidos en ~/.config/database-mcp/profiles.json (chmod 600). La IA puede añadir, cambiar, probar y eliminarlos sobre la marcha mediante herramientas — sin reiniciar el servidor:

• profile_add(name, dsn, allow_writes=false, description, make_default, test=true)

• profile_remove(name) · profile_test(name) · profiles()

• cada herramienta de consulta acepta un parámetro opcional profile; se usa el perfil predeterminado cuando se omite.

Los perfiles son de solo lectura por defecto (default_transaction_read_only a nivel de sesión); las escrituras requieren un perfil con allow_writes=true explícito.

Puente SSH

Un perfil puede alcanzar una base de datos que solo es accesible vía SSH (el clásico escenario "Postgres escucha en localhost de un host remoto"):

profile_add(name="prod", dsn="postgresql://app@dbhost:5432/app",
            ssh_host="dbhost")

• El túnel es un subproceso de ssh del sistema (-N -L, BatchMode, keepalives) — tu ~/.ssh/config, claves y agente se aplican sin cambios. La autenticación debe funcionar de forma no interactiva.

• ssh_remote_host/ssh_remote_port por defecto toman el host/puerto del DSN tal como se ve desde el host SSH; si el host del DSN es igual al host SSH, por defecto es 127.0.0.1 (el caso habitual).

• Los túneles se inician de forma perezosa, se comprueba su salud en cada uso y se reconstruyen automáticamente. Si un túnel muere a mitad de paginación, sus cursores se invalidan con un error claro y la siguiente consulta se reconecta.

• La multiplexación (ControlMaster) está explícitamente deshabilitada para conexiones de túnel, de modo que la vida del túnel sea exactamente la vida del subproceso.

Herramientas

Los resultados son JSON compacto — columnas una vez, filas como arrays — aproximadamente la mitad de los tokens del formato de diccionario por fila que emiten otros servidores. query también devuelve estimated_rows (estimación del planificador vía EXPLAIN) para que el modelo sepa en qué está paginando.

Instalación y ejecución

uv pip install -e .
database-mcp --dsn postgresql://user@host:5432/db      # registers profile "default"
database-mcp                                           # start empty, add profiles at runtime

Registro en Claude Code:

claude mcp add database -- database-mcp --dsn postgresql://user@host:5432/db

Opciones: --profiles FILE, --allow-writes, --page-size 50, --max-page-size 500, --max-page-bytes 32000, --max-cell 400, --cursor-ttl 300, --max-cursors 4, --statement-timeout 30, --keepalive 120, --connect-timeout 5. Entorno: DATABASE_MCP_DSN / DATABASE_URL, DATABASE_MCP_PROFILES.

Manejo de conexiones obsoletas

Las conexiones muertas se detectan rápidamente en cada capa en lugar de colgarse:

• Túneles SSH: ServerAliveInterval = --keepalive (por defecto 2 min) con ServerAliveCountMax=1 — una sonda perdida termina el proceso del túnel, que el gestor del motor detecta en el siguiente uso y reconstruye de forma perezosa.

• Conexiones de base de datos: keepalives TCP (keepalives_idle = --keepalive, sondas cada 10 s, 3 fallos) detectan pares muertos en ~30 s — incluyendo conexiones de cursor fijadas fuera del pool.

• Comprobación de checkout del pool: cada conexión entregada se valida con un viaje de ida y vuelta barato; una obsoleta se descarta y se reemplaza de forma transparente — el llamador nunca ve el error. Las conexiones inactivas del pool se reciclan después de --keepalive segundos; los intentos de conexión fallan después de --connect-timeout (por defecto 5 s) en lugar del ~2 min por defecto de TCP.

Pruebas

uv pip install -e '.[dev]'
pytest            # needs a local PostgreSQL (DBMCP_TEST_DSN to override)

Licencia

MIT