pg-guard-mcp

A PostgreSQL MCP server that enforces read-only access at the protocol and privilege level — not by parsing the query string and hoping.

Install

pip install pg-guard-mcp
# or, without installing anything permanently:
uvx pg-guard-mcp

Why this exists

The official @modelcontextprotocol/server-postgres shipped a read-only mode that a single COMMIT; could bypass: it wrapped the agent's query in BEGIN TRANSACTION READ ONLY and sent the whole thing as one string. Postgres accepts semicolon-separated multiple statements in that mode, so SELECT 1; COMMIT; DROP SCHEMA public CASCADE; closed the read-only transaction early and ran the drop as an ordinary write. The package was deprecated over it. (Datadog Security Labs writeup)

pg-guard-mcp exists because that bug class — "read-only" enforced only by string inspection — is still common across the MCP ecosystem. It defends in three independent layers, so no single mistake is fatal:

1. Protocol layer (the real boundary). Every query runs through Postgres's extended query protocol (Parse/Bind/Execute), never the simple query protocol. The extended protocol structurally rejects more than one statement per Parse message — Postgres itself refuses it, before any of our code runs. This is why the Datadog exploit cannot work here regardless of what string is submitted.
2. Session layer. Every connection sets default_transaction_read_only = on at the session level, so even a query that somehow reached the database as a write is rejected by Postgres.
3. Pre-flight layer. Before a query is even sent, it's checked for multiple statements and transaction-control keywords (COMMIT, ROLLBACK, BEGIN, SAVEPOINT, ...) and rejected with a clear error. This exists to fail fast and loud, not as the primary defense.

On top of that, connecting with a database role that has had write privileges REVOKEd is the recommended (and startup-checked) setup — belt and suspenders at the privilege layer too.

Tools

Migration safety linting

An agent asked to "add this migration and run it" is exactly the moment a CREATE INDEX without CONCURRENTLY locks writes on a busy table for the next ten minutes, or an ADD COLUMN ... NOT NULL with no default fails outright the instant it hits a populated table. pg_check_migration_safety and pg_check_migration_file catch these before they run — pure text analysis, no database connection involved, so they work with no PG_GUARD_DSN configured at all.

This is the same rule class as Squawk and strong_migrations, which exist as standalone linters but not, as far as a deliberate search turned up, as an MCP tool an agent can call mid-conversation:

This is regex-based pattern matching over one statement at a time, not a real SQL parser — see migration_safety.py's module docstring for the exact scope limitation (a single hand-written statement combining several actions in one comma-separated ALTER TABLE is checked as a whole, not action-by-action; every common migration tool generates one action per statement by default, so this covers the overwhelming majority of real-world migrations). An empty findings list means no known-unsafe pattern was found, not a guarantee.

Setup

pip install pg-guard-mcp
export PG_GUARD_DSN="host=127.0.0.1 dbname=mydb user=myapp_readonly password=..."
pg-guard-mcp

Point your MCP client at the pg-guard-mcp command (or uvx pg-guard-mcp to skip a permanent install) with PG_GUARD_DSN set in its env config.

See .env.example for all supported environment variables, and scripts/setup_dev_db.sh for a working example of setting up a properly-restricted read-only role (the setup this project's own tests run against).

Testing

pip install -e ".[dev]"
pytest tests/ -v

tests/test_safety.py is pure-Python and needs no database. tests/test_db.py and tests/test_server.py run against a real local PostgreSQL instance — including the exact exploit payload that deprecated the official Postgres MCP server — and skip automatically if pgguard_test isn't reachable. Run scripts/setup_dev_db.sh once to create it.

Status

v0.2.0. 99 passing tests (unit + live-Postgres integration, including the exact exploit that deprecated the official server-postgres, run against a fresh pip install of the published package) plus 16 DB-dependent tests that skip automatically without a local pgguard_test database.

License

MIT