postgres-mcp-server

Servidor MCP local para PostgreSQL. Está pensado para OpenCode y clientes MCP por stdio.

Objetivo: consultar e inspeccionar bases PostgreSQL con seguridad. La escritura y el mantenimiento vienen apagados por defecto.

Seguridad rápida

• POSTGRES_ENABLE_WRITE=false por defecto.
• POSTGRES_ENABLE_MAINTENANCE=false por defecto.
• Las consultas de lectura corren en BEGIN TRANSACTION READ ONLY.
• La introspección usa parámetros ($1, $2), no concatena nombres enviados por el usuario.
• Los logs van a stderr. stdout queda reservado para MCP.
• Los errores no imprimen contraseñas ni URLs completas con credenciales.

Instalación

npm install
npm run build

Configuración

Variables principales:

Variable	Default	Uso
POSTGRES_URL o DATABASE_URL	requerido	URL de conexión PostgreSQL.
POSTGRES_ENABLE_WRITE	false	Habilita INSERT, UPDATE, DELETE, MERGE, COPY.
POSTGRES_ENABLE_MAINTENANCE	false	Habilita DROP, TRUNCATE, ALTER, CREATE, VACUUM, ANALYZE, REINDEX, GRANT, REVOKE.
PG_STATEMENT_TIMEOUT_MS	30000	Tiempo máximo de sentencia.
PG_MAX_CONNECTIONS	10	Máximo de conexiones del pool.
TRANSACTION_TIMEOUT_MS	60000	Tiempo máximo de transacciones pendientes.
MAX_CONCURRENT_TRANSACTIONS	5	Máximo de transacciones de escritura abiertas.

También podés pasar la URL como primer argumento del binario.

OpenCode

Ejemplo seguro, sin secretos reales:

"DB_ejemplo": {
  "type": "local",
  "command": [
    "node",
    "D:/work/postgres-mcp-server/dist/index.js"
  ],
  "environment": {
    "POSTGRES_URL": "postgresql://USER:PASSWORD@HOST:5432/DB_NAME",
    "POSTGRES_ENABLE_WRITE": "false",
    "POSTGRES_ENABLE_MAINTENANCE": "false",
    "PG_STATEMENT_TIMEOUT_MS": "30000"
  },
  "enabled": true,
  "timeout": 60000
}

Si usás paquete instalado:

"command": ["npx", "-y", "postgres-mcp-server"]

Tools MCP

execute_query

Ejecuta SQL de lectura: SELECT, WITH, EXPLAIN, SHOW.

Entrada:

{ "sql": "SELECT now()" }

execute_dml_ddl_dcl_tcl

Ejecuta escritura solo si POSTGRES_ENABLE_WRITE=true. Deja la transacción abierta y devuelve transaction_id.

Entrada:

{ "sql": "UPDATE users SET active = true WHERE id = 1" }

Después llamá a execute_commit o execute_rollback.

execute_commit

Confirma una transacción pendiente.

{ "transaction_id": "tx_..." }

execute_rollback

Revierte una transacción pendiente.

{ "transaction_id": "tx_..." }

execute_maintenance

Ejecuta mantenimiento solo si POSTGRES_ENABLE_MAINTENANCE=true.

list_schemas

Lista esquemas no internos visibles para el usuario conectado.

list_tables

Lista tablas. Acepta filtro opcional:

{ "schema_name": "public" }

describe_table

Describe columnas, índices y constraints.

{ "schema_name": "public", "table_name": "users" }

Desarrollo

npm ci
npm run build
npm test -- --run --coverage
npm run lint

Los tests usan fakes/mocks. No necesitan una base PostgreSQL real.

CI

GitHub Actions ejecuta Node 20 y 22 con cache npm, build, lint y coverage. El mínimo es 85% en líneas, funciones, ramas y statements.

Más documentación

• docs/configuracion.md
• docs/seguridad-sql.md
• docs/desarrollo.md