pgmcp

pgmcp es un servidor de operaciones/DBA de PostgreSQL de solo lectura para el Model Context Protocol, construido sobre el oficial modelcontextprotocol/go-sdk. Responde a las preguntas que un DBA se hace durante un incidente — qué sentencias son lentas, por qué un plan es lento, qué índices son un lastre, en qué tablas se ha quedado atrás autovacuum, quién está bloqueando a quién, cuánto retraso lleva el standby — y es de solo lectura por oficio, no por convención: un rol de base de datos dedicado sin privilegio de escritura, una transacción BEGIN READ ONLY con un timeout de sentencia para cada sentencia, y un analizador de SQL que actúa como guardián y rechaza todo lo que no sea un único SELECT/EXPLAIN/SHOW y cualquier función que pueda mutar el estado desde dentro de una transacción de solo lectura. Probado contra PostgreSQL 16; requiere la versión 13 o posterior.

Instalación

Claude Desktop, de un clic: descarga pgmcp_<version>.mcpb desde Releases y ábrelo. Claude Desktop te pide una cadena de conexión de Postgres, la guarda en el llavero del sistema operativo y arranca el binario incluido — no hay nada en PATH, ningún archivo de configuración que editar. Un solo paquete cubre macOS (universal) y Windows (x64).

De lo contrario, descarga un binario para tu plataforma desde las Releases — darwin, linux y windows, amd64 y arm64, con checksums.

O compílalo desde el código fuente con la herramienta CLI de Go go:

go install github.com/pascalallen/pgmcp/cmd/pgmcp@latest

O ejecuta la imagen publicada, que es distroless, sin root y multi-arquitectura:

docker run --rm -i -e PGMCP_DATABASE_URL='postgres://…' ghcr.io/pascalallen/pgmcp

pgmcp está listado en el Registro MCP como io.github.pascalallen/pgmcp.

Antes de apuntarlo a cualquier base de datos, crea el rol de solo lectura — ver Rol de base de datos. Es la capa que sigue manteniendo la seguridad si las otras dos tienen un bug.

Related MCP server: PostgreSQL MCP Server

Uso

Una superficie MCP, dos transportes. Cuál de ellos se ejecuta es una cuestión de configuración, no una compilación distinta.

Claude Code, stdio — el cliente lanza el binario y habla por stdin/stdout:

claude mcp add pgmcp --transport stdio \
  --env PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
  -- pgmcp

Claude Desktop, stdio — instala el paquete .mcpb desde Releases (ver Instalación), o escribe lo mismo a mano en claude_desktop_config.json:

{
  "mcpServers": {
    "pgmcp": {
      "command": "pgmcp",
      "env": {
        "PGMCP_DATABASE_URL": "postgres://pgmcp:…@db.internal:5432/app?sslmode=require"
      }
    }
  }
}

HTTP — HTTP Streamable detrás de una clave estática de tipo bearer, para una implementación compartida. pgmcp habla HTTP simple y nunca termina TLS por sí mismo; ejecútalo en un bucle local detrás de un proxy inverso.

PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
PGMCP_AUTH_MODE=static \
PGMCP_API_KEYS="$(openssl rand -hex 32)" \
  pgmcp --transport http --listen 127.0.0.1:8080

claude mcp add pgmcp --transport http https://pgmcp.example.com/mcp \
  --header "Authorization: Bearer <key>"

La terminación TLS, los ajustes de proxy que necesita el transporte de streaming, la autenticación JWT contra un proveedor de identidad y la conexión de pgmcp como un conector personalizado de claude.ai se encuentran todos en docs/DEPLOYING.md.

Herramientas

Cada herramienta está anotada con readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false y devuelve un esquema de salida tipado.

query es la única herramienta que permite SQL libre, por lo que es opcional. --disable-query la elimina por completo del catálogo: una implementación que solo necesita las ocho herramientas de diagnóstico puede ejecutarse sin superficie SQL ad hoc. --query-schemas=public,app la restringe a los esquemas nombrados, y limita también explain, ya que analyze=true ejecuta la sentencia; lee sobre qué se impide y qué no se impide en docs/SECURITY.md.

Recursos y prompt

Configuración

Cada ajuste tiene un flag --flag y una variable de entorno PGMCP_<KEY>. Las flags tienen prioridad sobre la variable de entorno y esta sobre el valor predeterminado. Los errores de configuración salen con el código 2 y se indica el nombre de cada clave problemática en un único mensaje; los fallos en tiempo de ejecución salen con el código 1.

El bloque de autenticación se aplica solo al transporte HTTP. Con stdio, el sistema operativo decide quién es el llamador: el proceso padre que lanzó el binario, y nadie más.

Modelo de seguridad

• Solo lectura de tres formas independientes. Un rol dedicado sin privilegio de escritura (pg_monitor más SELECT, y deliberadamente no pg_signal_backend); BEGIN READ ONLY con SET LOCAL statement_timeout y lock_timeout = '2s' alrededor de cada sentencia que ejecuta el adaptador, siempre con rollback; y una protección a nivel de analizador sintáctico, porque una transacción de solo lectura por sí sola no detiene pg_terminate_backend, pg_read_file, pg_sleep ni setval.

• El guardián SQL es ante todo una lista de permitidos. Una única sentencia de nivel superior, y debe ser un SELECT, EXPLAIN o SHOW; ninguna sentencia de escritura anidada en ningún lugar del árbol; ninguna cláusula de bloqueo FOR UPDATE/FOR SHARE; ningún SELECT INTO; y ninguna llamada a una función denegada: acceso a archivos, control de copias de seguridad y WAL, slots de replicación, bloqueos de asesoramiento, dblink, mutación de secuencias, reinicios de estadísticas.

• La lista de esquemas permitidos es una barrera de protección, no un límite. --query-schemas coincide con los esquemas que califican las referencias a tablas en la sentencia analizada, sin distinguir mayúsculas de minúsculas, y limita ambas herramientas que transportan SQL proporcionado por el llamador — query y explain, de modo que explain con analyze=true no puede ejecutarse contra un esquema que hayas excluido. Una vista, una función que devuelve un conjunto, o una función SECURITY DEFINER dentro de un esquema permitido aún puede leer fuera de él. Los privilegios de la base de datos son el límite; la lista de permitidos solo estrecha el camino obvio.

• Autenticado, con cierre ante fallos, sobre HTTP. Las claves estáticas se comparan en tiempo constante contra cada hash almacenado sin salida anticipada; los JWT se validan contra un conjunto JWK solo con algoritmos asimétricos (sin alg=none, sin confusión HMAC) y con iss, aud y exp obligatorios, y el verificador no tiene claves hasta que llega el JWKS, por lo que arranca cerrado en lugar de abierto. Los metadatos de recurso protegido de RFC 9728 anuncian dónde obtener un token. El servidor se niega a arrancar en una dirección que no sea de bucle local con la autenticación desactivada.

• Acotado. Limitación de frecuencia por principal, un tiempo de espera por llamada, un tiempo de espera de sentencia y de bloqueo dentro de la transacción, un límite de filas en la herramienta query, un límite en el contenido estructurado de un resultado y un límite de 1 MiB en el cuerpo de la petición.

• No se registra nada sensible. Una llamada a una herramienta registra su nombre, duración, resultado y el id de usuario del llamador; nunca argumentos, texto SQL, filas de resultados ni texto de error. Los fallos de análisis devuelven una frase fija en lugar de repetir la sentencia, y el DSN se oculta en los errores de conexión.

El modelo de amenazas, la enumeración completa de las capas y las limitaciones que cada una no cubre están en docs/SECURITY.md.

Pruebas

Ejecuta la suite de pruebas con el detector de condiciones de carrera y la cobertura:

go test -race -cover ./...

Las pruebas de integración necesitan una base de datos Postgres y se omiten cuando PGMCP_TEST_DSN no está definido. Para ejecutarlas contra un Postgres de prueba con pg_stat_statements precargado:

docker run -d --rm --name pg -e POSTGRES_PASSWORD=postgres -p 5544:5432 postgres:16 \
  -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all
docker exec pg psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements"
PGMCP_TEST_DSN="postgres://postgres:postgres@localhost:5544/postgres?sslmode=disable" go test -race -cover ./...

Crea y visualiza un perfil de cobertura:

go test -covermode=count -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Pasa un servidor en ejecución por la suite oficial de conformidad de MCP, o hazle una prueba de humo con el Inspector:

npx -y @modelcontextprotocol/conformance server --url http://127.0.0.1:8080/mcp \
  --expected-failures .github/conformance-expected-failures.yaml
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8080/mcp --transport http --method tools/list

Contribuciones

Las pull requests son bienvenidas. Para cambios importantes, abre primero un issue para discutir lo que te gustaría cambiar.

Asegúrate de actualizar las pruebas según corresponda.

Licencia

MIT