pgops-mcp

Un servidor MCP de grado de producción que brinda a los agentes de IA un control seguro, auditado y de nivel experto sobre una base de datos PostgreSQL real y el stack de Docker que la rodea: sin comandos de shell, sin scripts de Python, solo herramientas.

Por qué

Los servidores MCP de Postgres existentes son envoltorios de consultas simples: introspect + SELECT. Ninguno maneja migraciones con análisis de impacto de bloqueos, ninguno diagnostica el rendimiento desde EXPLAIN + pg_stat_statements, ninguno entiende el entorno contenedorizado en el que vive la base de datos. Los agentes que operan bases de datos hoy en día están volando a ciegas y de forma insegura.

pgops-mcp es el cerebro de operaciones: inteligencia de esquema → consultas protegidas → motor de migraciones → diagnóstico de rendimiento → conciencia del entorno, con una arquitectura de seguridad que hace que cada acción sea clasificable, confirmable y auditable.

Related MCP server: PostgreSQL MCP Server

Superficie de herramientas (v0.1)

* No se registran en absoluto a menos que el servidor se ejecute con --approval-mode, e incluso entonces cada llamada necesita un token de confirmación. container.exec además impone una lista blanca de comandos de diagnóstico de solo lectura: no ofrece un shell. El socket de Docker es equivalente a root en el host, por lo que el acceso predeterminado es de solo lectura.

Modelo de seguridad (el diferenciador principal)

• Roles de conexión separados de solo lectura / lectura-escritura; las herramientas se vinculan al rol correcto

• Clasificación de declaraciones antes de la ejecución: se bloquean DELETE/UPDATE sin límite

• Las acciones destructivas requieren tokens de confirmación explícitos

• Cada declaración ejecutada se registra en un registro de auditoría de solo anexión con tiempo y veredicto

• Cancelación de consultas descontroladas con niveles de tiempo de espera

Superficie MCP

Acceso remoto y tokens de agente

stdio no necesita autenticación: el servidor es un subproceso que tu cliente inicia, sin puerto abierto. HTTP sí la necesita, por lo que se niega a iniciar sin una clave:

pgops-mcp keygen                                    # RS256 keypair
pgops-mcp issue-token --subject my-agent            # read-only by default
pgops-mcp issue-token --subject deploy-bot --scope pgops:read --scope pgops:write
pgops-mcp scopes                                    # which scope each tool needs

pgops-mcp --transport http --public-key ~/.pgops/keys/pgops_public.pem

El servidor solo tiene la clave pública, por lo que puede verificar tokens pero nunca acuñarlos. Los ámbitos (pgops:read / pgops:write / pgops:admin) se asignan a los mismos niveles de peligro que las protecciones, y una herramienta sin entrada de ámbito requiere admin — denegar por defecto. Se vincula a loopback a menos que se indique lo contrario.

Inicio rápido

uv sync
# point at your local Postgres in Docker:
export PGOPS_DSN="postgresql://user:pass@localhost:5432/mydb"
uv run pgops-mcp            # stdio transport for Claude Desktop / Cursor / VS Code

Añade a Claude Desktop:

{
  "mcpServers": {
    "pgops": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pgops-mcp", "pgops-mcp"]
    }
  }
}

Documentación

• docs/PRD.md — qué y por qué, objetivos, no objetivos

• docs/SPEC.md — especificación técnica por fases con puertas duras

• docs/ARCHITECTURE.md — diseño del sistema y compensaciones

• docs/TOOLS.md — catálogo completo de herramientas con esquemas y ejemplos

• docs/adr/ — registros de decisiones de arquitectura

• docs/flow.md — registro de progreso vivo

• docs/interview_prep.md — Q&A de entrevista en crecimiento

Estado

Fases 0–6b completas (319 pruebas, cada protección, veredicto y regla de impacto de bloqueo probados contra Postgres real mediante testcontainers — sin mocks — además de suites de extremo a extremo que ejecutan el servidor como un subproceso MCP real sobre stdio y como un servidor HTTP autenticado).

migration.rollback está deliberadamente aún abierto — consulta docs/TOOLS.md.

Ejemplo de lo que devuelve migration.plan para un cambio de tipo en los orders de 1.2M filas:

ALTER TABLE "orders" ALTER COLUMN "total_cents" TYPE bigint
  op=table_rewrite  risk=high  estimate=4800ms  confidence=medium
  why:   rewrites every row and rebuilds every index, holding AccessExclusiveLock
  SAFER: add a new column of the target type, backfill in batches, sync with a
         trigger, swap the names, then drop the old column

Inicia rápidamente la base de datos de desarrollo (puerto del host 5433, para evitar colisionar con un Postgres local en 5432):

docker compose up -d
export PGOPS_DSN="postgresql://pgops:pgops_dev@localhost:5433/pgops_demo"
uv run pgops-mcp --selfcheck