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.

Related MCP server: postgres-mcp

Instalación

npm install
npm run build

Configuración

Variables principales:

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