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.

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

Setup

pip install -e ".[dev]"
export PG_GUARD_DSN="host=127.0.0.1 dbname=mydb user=myapp_readonly password=..."
python -m pg_guard_mcp.server

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

Early build, 58 passing tests (unit + live-Postgres integration). Not yet published to PyPI.

License

MIT