pgmcp MCP server

pgmcp

pgmcp is a read-only PostgreSQL ops/DBA server for the Model Context Protocol, built on the official modelcontextprotocol/go-sdk. It answers the questions a DBA asks during an incident — which statements are slow, why this plan is slow, which indexes are dead weight, which tables autovacuum has fallen behind on, who is blocking whom, how far the standby is lagging — and it is read-only by construction rather than by convention: a dedicated database role that holds no write privilege, a BEGIN READ ONLY transaction with a statement timeout around every single statement, and a SQL parser guard that rejects anything that is not one SELECT/EXPLAIN/SHOW and every function that could mutate state from inside a read-only transaction. Tested against PostgreSQL 16; requires 13 or later.

Installation

Claude Desktop, one click: download pgmcp_.mcpb from Releases and open it. Claude Desktop asks for a Postgres connection string, keeps it in the OS keychain, and launches the bundled binary itself — nothing on PATH, no config file to edit. One bundle covers macOS (universal) and Windows (x64).

Otherwise download a binary for your platform from Releases — darwin, linux and windows, amd64 and arm64, with checksums.

Or build from source with the Go CLI tool go:

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

Or run the released image, which is distroless, non-root and multi-arch:

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

pgmcp is listed in the MCP Registry as io.github.pascalallen/pgmcp.

Before you point it at anything, create the read-only role — see Database role. It is the layer that still holds if the other two have a bug.

Usage

One MCP surface, two transports. Which one you run is configuration, not a different build.

Claude Code, stdio — the client launches the binary and talks over stdin/stdout:

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

Claude Desktop, stdio — install the .mcpb bundle from Releases (see Installation), or write the same thing into claudedesktopconfig.json by hand:

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

HTTP — Streamable HTTP behind a static bearer key, for a shared deployment. pgmcp speaks plain HTTP and never terminates TLS itself; run it on loopback behind a reverse proxy.

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

Shortened. The full README is on GitHub.