pgmcp

pgmcp ist ein schreibgeschützter PostgreSQL-Ops-/DBA-Server für das Model Context Protocol, der auf dem offiziellen modelcontextprotocol/go-sdk aufbaut. Er beantwortet die Fragen, die ein DBA während eines Vorfalls stellt – welche Anweisungen langsam sind, warum dieser Plan langsam ist, welche Indizes überflüssig sind, bei welchen Tabellen autovacuum hinterherhinkt, wer wen blockiert, wie weit der Standby zurückliegt – und er ist konstruktionsbedingt schreibgeschützt, nicht nur durch Konvention: eine dedizierte Datenbankrolle ohne Schreibrechte, eine BEGIN READ ONLY-Transaktion mit einem Statement-Timeout für jede einzelne Anweisung und ein SQL-Parser-Guard, der alles ablehnt, was nicht ein SELECT/EXPLAIN/SHOW ist, sowie jede Funktion, die innerhalb einer Read-Only-Transaktion Zustand mutieren könnte. Getestet gegen PostgreSQL 16; erfordert Version 13 oder neuer.

Installation

Claude Desktop, mit einem Klick: Laden Sie pgmcp_<version>.mcpb von Releases herunter und öffnen Sie es. Claude Desktop fragt nach einer Postgres-Verbindungszeichenfolge, bewahrt sie im Schlüsselbund des Betriebssystems auf und startet die gebündelte Binärdatei selbst – nichts im PATH, keine Konfigurationsdatei zum Bearbeiten. Ein Bundle deckt macOS (universal) und Windows (x64) ab.

Andernfalls laden Sie eine Binärdatei für Ihre Plattform von Releases herunter – darwin, linux und windows, amd64 und arm64, mit Prüfsummen.

Oder bauen Sie mit dem Go-CLI-Tool go aus dem Quellcode:

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

Oder führen Sie das veröffentlichte Image aus, das distroless, nicht-root und multi-arch ist:

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

pgmcp ist im MCP-Registry als io.github.pascalallen/pgmcp gelistet.

Bevor Sie es mit etwas verbinden, erstellen Sie die schreibgeschützte Rolle – siehe Datenbankrolle. Sie ist die Ebene, die auch dann noch hält, wenn die anderen beiden einen Fehler haben.

Related MCP server: PostgreSQL MCP Server

Verwendung

Eine MCP-Oberfläche, zwei Transporte. Welchen Sie ausführen, ist eine Frage der Konfiguration, kein anderer Build.

Claude Code, stdio – der Client startet die Binärdatei und kommuniziert über stdin/stdout:

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

Claude Desktop, stdio – installieren Sie das .mcpb-Bundle aus Releases (siehe Installation) oder schreiben Sie dasselbe von Hand in claude_desktop_config.json:

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

HTTP – Streamable HTTP hinter einem statischen Bearer-Key für eine gemeinsame Bereitstellung. pgmcp spricht reines HTTP und terminiert TLS nie selbst; führen Sie es hinter einem Reverse-Proxy auf Loopback aus.

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>"

TLS-Terminierung, die Proxy-Einstellungen, die der Streaming-Transport benötigt, JWT-Authentifizierung gegen einen Identitätsanbieter und die Anbindung von pgmcp als benutzerdefinierter Connector für claude.ai befinden sich alle in docs/DEPLOYING.md.

Tools

Jedes Tool ist mit readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false annotiert und gibt ein typisiertes Ausgabeschema zurück.

query ist das einzige Tool, das frei formuliertes SQL enthält, und es ist optional. --disable-query entfernt es vollständig aus dem Katalog – eine Bereitstellung, die nur die acht Diagnose-Tools benötigt, kann ganz ohne Ad-hoc-SQL-Oberfläche betrieben werden. --query-schemas=public,app beschränkt es stattdessen auf benannte Schemas – und begrenzt damit auch explain, da analyze=true die Anweisung ausführt; lesen Sie in docs/SECURITY.md, was das verhindert und was nicht.

Ressourcen & Prompt

Konfiguration

Jede Einstellung hat ein --flag und eine Umgebungsvariable PGMCP_<KEY>. Flags haben Vorrang vor der Umgebung, die Vorrang vor dem Standardwert hat. Konfigurationsfehler beenden mit Exit-Code 2 und nennen jeden fehlerhaften Schlüssel in einer Meldung; Laufzeitfehler beenden mit Exit-Code 1.

Der Auth-Block gilt nur für den HTTP-Transport. Über stdio entscheidet das Betriebssystem, wer der Aufrufer ist: der übergeordnete Prozess, der die Binärdatei gestartet hat, und sonst niemand.

Sicherheitsmodell

• Nur-Lesen auf drei unabhängige Arten. Eine dedizierte Rolle ohne Schreibberechtigung (pg_monitor plus SELECT, und bewusst nicht pg_signal_backend); BEGIN READ ONLY mit SET LOCAL statement_timeout und lock_timeout = '2s' wird für jede Anweisung, die der Adapter ausführt, verwendet und stets zurückgerollt; und ein Parser-Guard, denn eine Nur-Lesen-Transaktion allein stoppt pg_terminate_backend, pg_read_file, pg_sleep oder setval nicht.

• Die SQL-Guard setzt in erster Linie auf eine Allowlist. Eine einzelne Top-Level-Anweisung, und sie muss ein SELECT, EXPLAIN oder SHOW sein; keine verschachtelte Schreibanweisung irgendwo im Syntaxbaum; keine FOR UPDATE/FOR SHARE-Sperrklausel; kein SELECT INTO; und kein Aufruf einer verbotenen Funktion — Dateizugriff, Backup- und WAL-Kontrolle, Replikations-Slots, Advisory Locks, dblink, Sequenz-Mutation, Stats-Resets.

• Die Schema-Allowlist ist eine Leitplanke, keine Grenze. --query-schemas gleicht die Schemas ab, die Tabellenreferenzen in der geparsten Anweisung qualifizieren, ohne Beachtung der Groß- und Kleinschreibung, und sie begrenzt beide Tools, die vom Aufrufer geliefertes SQL ausführen — query und explain, sodass explain mit analyze=true nicht gegen ein Schema ausgeführt werden kann, das du ausgeschlossen hast. Eine View, eine set-returning Funktion oder eine SECURITY DEFINER-Funktion innerhalb eines erlaubten Schemas kann trotzdem außerhalb davon lesen. Datenbank-Berechtigungen sind die Grenze; die Allowlist verengt nur den offensichtlichen Weg.

• Authentifiziert, fail-closed, über HTTP. Statische Schlüssel werden in konstanter Zeit gegen jeden gespeicherten Hash verglichen, ohne vorzeitigen Abbruch; JWTs werden gegen einen JWK-Satz mit ausschließlich asymmetrischen Algorithmen validiert (kein alg=none, keine HMAC-Verwechslung) und mit erforderlichen iss, aud und exp; und der Verifizierer hält keine Schlüssel, bis das JWKS eintrifft, sodass er geschlossen statt offen startet. Die Metadaten der geschützten Ressource aus RFC 9728 geben an, wo ein Token bezogen werden kann. Der Server weigert sich, auf einer Nicht-Loopback-Adresse mit deaktivierter Authentifizierung zu starten.

• Begrenzt. Rate-Limiting pro Prinzipal, ein Timeout pro Aufruf, ein Statement-Timeout und ein Lock-Timeout innerhalb der Transaktion, eine Zeilenobergrenze für das query-Tool, eine Obergrenze für den strukturierten Inhalt eines Ergebnisses und ein 1-MiB-Limit für den Request-Body.

• Es wird nichts Sensibles protokolliert. Ein Tool-Aufruf protokolliert seinen Namen, seine Dauer, sein Ergebnis und die Benutzer-ID des Aufrufers — niemals Argumente, SQL-Text, Ergebniszeilen oder Fehlertext. Parse-Fehler werden als feste Phrase zurückgegeben, statt die Anweisung wiederzugeben, und die DSN wird aus Verbindungsfehlern entfernt.

Das Bedrohungsmodell, die vollständige Auflistung der Schichten und die Einschränkungen, die jede einzelne nicht abdeckt, finden sich in docs/SECURITY.md.

Tests

Führe die Testsuite mit Race-Detektor und Coverage aus:

go test -race -cover ./...

Integrationstests benötigen eine Postgres-Datenbank und werden übersprungen, wenn PGMCP_TEST_DSN nicht gesetzt ist. Um sie gegen eine temporäre Postgres-Datenbank mit vorab geladenem pg_stat_statements auszuführen:

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 ./...

Erstelle und betrachte ein Coverage-Profil:

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

Führe einen laufenden Server durch die offizielle MCP-Konformitätssuite oder mache einen Smoke-Test mit dem 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

Mitwirken

Pull Requests sind willkommen. Für größere Änderungen öffne bitte zuerst ein Issue, um zu besprechen, was du ändern möchtest.

Bitte stelle sicher, dass die Tests entsprechend aktualisiert werden.

Lizenz

MIT