db-mcp-server

Un servidor MCP local que brinda a un asistente de codificación con IA (p. ej. Claude Code) acceso aislado de credenciales a tus bases de datos PostgreSQL. El asistente envía solo SQL y recibe solo filas: los nombres de usuario, contraseñas y claves SSH de la base de datos nunca entran en el contexto del modelo ni en la transcripción de la conversación.

Por qué

Conectar un asistente de IA a una base de datos normalmente implica poner cadenas de conexión y contraseñas en algún lugar donde el modelo (y su transcripción) pueda leerlas. Este servidor mantiene ese límite: posee las credenciales cifradas y los túneles SSH, expone una pequeña superficie de herramientas solo SQL y, por defecto, es de solo lectura.

Related MCP server: Postgres Scout MCP

Cómo funciona

• Catálogo (registry.yaml) — enrutamiento no secreto. Organizado como clientes → entornos → servicios; cada servicio se asigna a un nombre de base de datos y a un secret_ref (un puntero a la bóveda, nunca una credencial).

• Bóveda (vault.enc) — AES-256-GCM con una clave derivada de scrypt. Contiene las credenciales de la base de datos, descifradas en memoria una vez al inicio usando una frase de contraseña.

• Grupo de túneles — un túnel SSH por (cliente, entorno) mediante sshtunnel, vinculado a un puerto efímero 127.0.0.1.

• Ejecutor — psycopg. run_query se ejecuta en una transacción de PostgreSQL SOLO LECTURA (el motor rechaza cualquier escritura); run_write_query requiere confirm=true.

Instalar

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1   (bash: source .venv/Scripts/activate)
pip install -e ".[dev]"

Configurar

La configuración proviene de variables de entorno; los valores predeterminados se resuelven en relación con la raíz del proyecto.

Aprovisionamiento (configuración inicial)

1. Copia la plantilla y completa los valores reales:

   cp bootstrap.example.yaml bootstrap.yaml

2. Coloca tus claves privadas SSH en keys/ (los nombres de archivo deben coincidir con los campos pem_key del catálogo).

3. Genera el catálogo no secreto y la bóveda cifrada (solicita la frase de contraseña que reutilizarás para ejecutar el servidor):

   python -m db_mcp_server.bootstrap --dry-run   # preview, writes nothing
   python -m db_mcp_server.bootstrap             # writes registry.yaml + vault.enc
   python -m db_mcp_server.vault_admin verify     # expect {"ok": true}

bootstrap.yaml contiene credenciales en texto plano — está en git-ignore; elimínalo o mantenlo fuera de línea una vez que exista la bóveda.

Herramientas de línea de comandos

(Los comandos de consola existen después de pip install -e .; la forma python -m db_mcp_server.<module> siempre funciona.)

Herramientas expuestas al asistente

• list_databases() — el catálogo (clientes → entornos → servicios); sin secretos.

• run_query(customer, environment, service, sql, max_rows?) — solo lectura.

• run_write_query(customer, environment, service, sql, confirm) — escritura controlada.

Los fallos de dominio se devuelven como un {error_code, message} estructurado en lugar de una excepción, para que el asistente pueda reaccionar.

Registro con un cliente MCP

Ejemplo de .mcp.json (ajusta las rutas). Usa ${DB_MCP_PASSPHRASE} para que la frase de contraseña se lea del shell en lugar de escribirse en el archivo:

{
  "mcpServers": {
    "db": {
      "command": "/absolute/path/to/db-mcp-server/.venv/Scripts/python.exe",
      "args": ["-m", "db_mcp_server.server"],
      "env": {
        "DB_MCP_PASSPHRASE": "${DB_MCP_PASSPHRASE}"
      }
    }
  }
}

Notas de seguridad

• vault.enc, keys/, bootstrap.yaml, *.env y *.pem están en git-ignore — nunca los confirmes.

• La frase de contraseña de la bóveda se suministra mediante DB_MCP_PASSPHRASE (o un aviso) — nunca se almacena en registry.yaml, argv o registros.

• db-vault lee la contraseña de la base de datos mediante un aviso oculto (getpass), nunca mediante argv.

• run_query es de solo lectura a nivel del motor de PostgreSQL; las escrituras requieren confirm=true.

Pruebas

pip install -e ".[dev]" && python -m pytest -q

La prueba de integración de la base de datos se omite a menos que DB_MCP_TEST_DSN apunte a un PostgreSQL accesible.

Hoja de ruta (no en esta versión)

Registro de auditoría persistente, operación multiusuario, respaldo de administrador de secretos externo, herramientas de introspección de esquema y una lista de denegación de permisos para convertir el aislamiento de credenciales en un límite estricto.