Postgres DBA MCP

Bounded, read-only PostgreSQL access for AI assistants.

Let Claude Code, Codex or any MCP client explore a PostgreSQL database, run SQL, read query plans, test hypothetical indexes, find the slowest queries and check the database's health, without flooding the model's context or escaping read-only mode.

A Model Context Protocol server that gives an AI client compact, bounded access to one PostgreSQL database. It is a drop-in replacement for crystaldba/postgres-mcp 0.3.0, with its nine tools under the same names and the same parameters, plus analyze_locks of its own, in one static binary. Switching is one line of client configuration; what the model receives changes (compact CSV, bounded results, one statement per call), as listed in MIGRATION.md.

Why

crystaldba/postgres-mcp gives an assistant the right DBA tools: schema, SQL, plans with hypothetical indexes, top queries, health checks, index advice. Three things got in the way of using it every day:

• Unbounded, verbose results. Rows come back as Python repr with no size limit. A plain SELECT on a big table returns hundreds of thousands of tokens, or fails.
• A restricted mode that can be bypassed. Function names are not checked in FROM, so a "read-only" call can still run functions such as pg_read_file or pg_advisory_lock (CVE-2026-85620).
• Weight. A Python container of about 300 MB that sits at about 250 MB of memory.

What the model receives changes:

• compact CSV with an explicit footer, every result capped in rows, bytes and cell length, and every cut announced;
• a restricted mode, on by default, that parses each statement with PostgreSQL's own parser (libpg_query) and checks every function call anywhere in it, inside a read-only transaction;
• one static Go binary that starts in milliseconds.

Measured

Against crystaldba/postgres-mcp 0.3.0 on the same PostgreSQL 17 database and the same read-only role, measured on 959bb72 on 2026-11-01, except the agent tasks:

• 61 % fewer tokens per execute_sql response: median of the 4 scenarios both servers answered (S01, S04, S05, S06). Every result is capped at 32 kB, where crystaldba returns up to 268k tokens or fails;
• 131 of 131 attack statements refused in restricted mode, where crystaldba executes 10;
• 9 MB of memory against 246 MB, both in a Linux container; cold start of 13 ms for the binary run directly, against 2.3 s for crystaldba including docker run;
• 27 of 27 agent tasks solved with Claude Code, against 25 of 27 — the one dated measure here: 2026-10-22, on 0.1.0, before the volatility gate and before analyze_locks.

The other side: the tool definitions are 39 % larger (2732 tokens for ten tools against 1962 for crystaldba's nine), and the tokens of a whole agent task are comparable. Drop locks from --tools to get the 0.3.0 tool set exactly.

Method, every number (including where postgres-dba-mcp does worse) and charts: BENCHMARK.md. The harness that produced them is in bench, with its inputs: the data set in bench/data, the attack and legitimate corpora in testdata/safesql, and the scenarios and tasks listed in BENCHMARK.md. cd bench && go run ./cmd/bench all redoes the security, memory, cold start and scenario measures with no model account; exact token counts take --tokens=claude or an ANTHROPIC_API_KEY, and the agent tasks and their judge need the claude CLI. Prerequisites and what each level needs: bench/README.md.

What the model receives

The same SELECT * FROM types through both servers. crystaldba 0.3.0:

[{'id': 1, 'txt': 'hello', 'empty': '', 'num': Decimal('532.10'), 'arr': [1, 2], 'iv': datetime.timedelta(days=1, seconds=7200), 'ts': datetime.datetime(2026, 3, 2, 10, 14, tzinfo=zoneinfo.ZoneInfo(key='Etc/UTC')), 'bin': b'\xde\xad\xbe\xef'}, {'id': 2, 'txt': None, 'empty': None, 'num': None, 'arr': None, 'iv': None, 'ts': None, 'bin': None}]

postgres-dba-mcp:

id,txt,empty,num,arr,iv,ts,bin

1,hello,"",532.10,"{1,2}",1 day 02:00:00,2026-03-02 10:14:00+00,\xdeadbeef 2,\N,\N,\N,\N,\N,\N,\N -- 2 rows, 2 ms

Values keep their PostgreSQL text form, NULL (\N) stays distinct from an empty string, and the footer says how many rows came back and whether anything was cut.

Install

With Homebrew (macOS and Linux):

brew install a-lafon/tap/postgres-dba-mcp

With the install script (macOS and Linux, amd64 and arm64): it downloads the release archive, checks it against checksums.txt and puts the binary in ~/.local/bin (POSTGRES_DBA_MCP_INSTALL_DIR to change it, POSTGRES_DBA_MCP_VERSION=v0.1.0 for a given release):

curl -fsSL https://raw.githubusercontent.com/a-lafon/postgres-dba-mcp/main/install.sh | sh

With Docker (linux/amd64 and linux/arm64, non-root, no shell):

docker run -i --rm -e DATABASE_URI ghcr.io/a-lafon/postgres-dba-mcp:latest

localhost in the URI then means the container itself: on Docker Desktop use host.docker.internal, on Linux --network=host (see below).

From a release archive, Windows included: download the archive for your system from the releases page (darwin, linux and windows on amd64; darwin and linux also on arm64), check it against checksums.txt (SHA-256), and put the postgres-dba-mcp binary on your PATH.

With the Go toolchain (Go 1.26 or later): go install github.com/a-lafon/postgres-dba-mcp/cmd/postgres-dba-mcp@latest.

The Linux binaries and the image parse SQL with the native PostgreSQL parser (about 20 MB at start). The macOS and Windows binaries, and a plain go install, use a WASM copy of it, which peaks near 300 MB of memory at start and hands it back afterwards. With a C compiler, CGO_ENABLED=1 go install -tags pgquery_cgo,netgo,osusergo github.com/a-lafon/postgres-dba-mcp/cmd/postgres-dba-mcp@latest builds the native one.

Check the install with postgres-dba-mcp --version. When the shell does not find it, ~/.local/bin is not on your PATH: add it, or register the server with the full path.

Quick start with Claude Code

Register the server with the database URI in its environment:

claude mcp add pg --env DATABASE_URI=postgres://pgdba_ro:secret@localhost:5432/pgdba -- postgres-dba-mcp

Or put it in .mcp.json:

{

"mcpServers": { "pg": { "command": "postgres-dba-mcp", "env": { "DATABASE_URI": "${DATABASE_URI}" } } } }

The URI can also be the first argument (postgres-dba-mcp postgres://...). When both are given, DATABASE_URI wins. The server starts without connecting: the first tool call opens the connection.

Connection options in the URI (sslmode, sslrootcert, connect_timeout, …) are honoured, and so is search_path, which is applied to every transaction rather than sent at connection time, because a transaction pooler refuses it there. A server setting such as timezone is reported as ignored for the same reason. A misspelled TLS option is refused at startup instead: left alone it would read as a server setting, and the connection would fall back to an unchecked certificate.

Through Docker, localhost inside the container is the container itself, and the image does not rewrite it. On Docker Desktop use host.docker.internal in the URI; on Linux use --network=host or the address of the host on the bridge network.

{

"mcpServers": { "pg": { "command": "docker", "args": ["run", "-i", "--rm", "-e", "DATABASE_URI", "ghcr.io/a-lafon/postgres-dba-mcp:latest"], "env": { "DATABASE_URI": "postgres://pgdba_ro:secret@host.docker.internal:5432/pgdba" } } } }

Quick start with Codex

Register the server with the database URI in its environment:

codex mcp add pg --env DATABASE_URI=postgres://pgdba_ro:secret@localhost:5432/pgdba -- postgres-dba-mcp

Or put it in ~/.codex/config.toml:

[mcp_servers.pg]

command = "postgres-dba-mcp" env = { DATABASE_URI = "postgres://pgdba_ro:secret@localhost:5432/pgdba" }

Codex stops waiting for a tool after tool_timeout_sec (60 s by default). If you raise --statement-timeout above that, raise tool_timeout_sec in the same entry too.

Several databases

One process serves one database. To use several, add one server entry per database. Each entry gets its own tools, so you can write permission rules per server. Use a read-only role everywhere, and --access-mode=unrestricted only where writes are intended.

{

"mcpServers": { "pg-prod": { "command": "postgres-dba-mcp", "env": { "DATABASE_URI": "${PROD_DATABASE_URI}" } }, "pg-staging": { "command": "postgres-dba-mcp", "args": ["--access-mode=unrestricted"], "env": { "DATABASE_URI": "${STAGING_DATABASE_URI}" } } } }

In Claude Code, permission rules name the server, so the two entries above can be treated differently. For example, in .claude/settings.json, allow every tool of pg-prod and ask before each execute_sql on pg-staging:

{

"permissions": { "allow": ["mcppg-prod"], "ask": ["mcppg-staging__execute_sql"] } }

Credentials outside the URI

You do not have to put the password in the URI or in .mcp.json. The driver (pgx) reads the standard libpq sources itself; this server adds no option for them.

A URI without a password, with the password read from ~/.pgpass (or the file named by PGPASSFILE) or from PGPASSWORD:

DATABASE_URI=postgres://pgdba_ro@db.example.com:5432/pgdba

A ~/.pgpass line has the form host:port:database:user:password, and the file must not be readable by others (chmod 600). PGPASSWORD=... postgres-dba-mcp works the same way.

A named service from pg_service.conf (or the file named by PGSERVICEFILE):

DATABASE_URI="service=prod"

[prod]

host=db.example.com port=5432 dbname=pgdba user=pgdba_ro sslmode=verify-full

The password never appears in the server's log: the startup line shows user@host:port/db only.

Read-only role

In restricted mode the server refuses writes, but the Postgres role is the real barrier. Give the server a role that can only read:

CREATE ROLE pgdba_ro LOGIN PASSWORD 'change-me';

GRANT pg_read_all_stats TO pgdba_ro; -- pg_stat_statements text and other sessions' statistics GRANT USAGE ON SCHEMA public TO pgdba_ro; GRANT SELECT ON ALL TABLES IN SCHEMA public TO pgdba_ro; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO pgdba_ro; -- tables created later

Without pg_read_all_stats, analyze_locks still reports the pids, the locks and the chains, but the waits, states, transaction ages and query texts of other roles' sessions come back as \N and it says so in a -- session details hidden: grant pg_read_all_stats to … line. From PostgreSQL 15 on, a NOINHERIT member of pg_read_all_stats reads nothing either, and is reported the same way; PostgreSQL 14 grants it on membership alone. Either way the line appears only when the report really hides something.

Repeat the USAGE, SELECT and ALTER DEFAULT PRIVILEGES lines for every other schema