pgops-mcp

Ein produktionsreifer MCP-Server, der KI-Agenten sichere, geprüfte und fachkundige Kontrolle über eine echte PostgreSQL-Datenbank und den dazugehörigen Docker-Stack gibt — keine Shell-Befehle, keine Python-Skripte, nur Tools.

Warum

Bestehende Postgres-MCP-Server sind dünne Query-Wrapper: Introspection + SELECT. Keiner verwaltet Migrationen mit Lock-Impact-Analyse, keiner diagnostiziert Performance anhand von EXPLAIN + pg_stat_statements, keiner versteht die containerisierte Umgebung, in der die Datenbank lebt. Agenten, die heute Datenbanken bedienen, fliegen blind und unsicher.

pgops-mcp ist das Operations-Gehirn: Schema-Intelligenz → geschützte Queries → Migrations-Engine → Performance-Diagnose → Umgebungsbewusstsein, mit einer Sicherheitsarchitektur, die jede Aktion klassifizierbar, bestätigbar und prüfbar macht.

Related MCP server: PostgreSQL MCP Server

Tool-Oberfläche (v0.1)

* Werden nur registriert, wenn der Server mit --approval-mode läuft, und selbst dann benötigt jeder Aufruf ein Bestätigungstoken. container.exec erzwingt zusätzlich eine Read-only-Allowlist für Diagnosebefehle — es bietet keine Shell. Der Docker-Socket ist auf dem Host root-äquivalent, daher ist der Standard Read-only-Zugriff.

Sicherheitsmodell (das zentrale Unterscheidungsmerkmal)

• Getrennte Read-only-/Read-write-Verbindungsrollen; Tools sind an die richtige Rolle gebunden

• Statement-Klassifizierung vor der Ausführung — unbegrenzte DELETE/UPDATE werden blockiert

• Destruktive Aktionen erfordern explizite Bestätigungstokens

• Jedes ausgeführte Statement landet in einem Append-only-Audit-Log mit Zeitmessung und Urteil

• Abbruch von außer Kontrolle geratenen Queries mit Timeout-Stufen

MCP-Oberfläche

Remote-Zugriff & Agent-Tokens

stdio benötigt keine Authentifizierung — der Server ist ein Subprozess, den Ihr Client startet, ohne offenen Port. HTTP schon, daher weigert er sich, ohne Schlüssel zu starten:

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

Der Server hält nur den öffentlichen Schlüssel, kann also Tokens verifizieren, aber nie selbst erstellen. Scopes (pgops:read / pgops:write / pgops:admin) entsprechen denselben Gefahrenstufen wie die Schutzmechanismen, und ein Tool ohne Scope-Eintrag erfordert admin — Deny by Default. Bindet an Loopback, sofern nicht anders angegeben.

Schnellstart

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

Zu Claude Desktop hinzufügen:

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

Dokumentation

• docs/PRD.md — Was & Warum, Ziele, Nicht-Ziele

• docs/SPEC.md — Phasenweise technische Spezifikation mit harten Gates

• docs/ARCHITECTURE.md — Systemdesign + Trade-offs

• docs/TOOLS.md — Vollständiger Tool-Katalog mit Schemas & Beispielen

• docs/adr/ — Architektur-Entscheidungsprotokolle

• docs/flow.md — Laufendes Fortschrittsprotokoll

• docs/interview_prep.md — Wachsendes Interview-Fragen & Antworten

Status

Phasen 0–6b abgeschlossen (319 Tests, jede Schutzmaßnahme, jedes Urteil und jede Lock-Impact-Regel gegen echtes Postgres via testcontainers verifiziert — keine Mocks — plus End-to-End-Suiten, die den Server als echten MCP-Subprozess über stdio und als authentifizierten HTTP-Server betreiben).

migration.rollback ist bewusst noch offen — siehe docs/TOOLS.md.

Beispiel dafür, was migration.plan für eine Typänderung an der 1,2M-Zeilen-orders-Tabelle zurückgibt:

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

Schnellstart der Dev-Datenbank (Host-Port 5433, um eine lokale Postgres-Instanz auf 5432 nicht zu kollidieren):

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