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:
- 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 perParsemessage — 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. - Session layer. Every connection sets
default_transaction_read_only = onat the session level, so even a query that somehow reached the database as a write is rejected by Postgres. - 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
| Tool | Does |
|---|---|
pg_run_query(sql) |
Run one read-only statement, return rows |
pg_explain_query(sql) |
Return the query plan without running it |
pg_list_tables(schema="public") |
List tables/views in a schema |
pg_describe_table(table_name, schema="public") |
List a table's columns |
pg_check_privileges() |
Report any write grant the connected role actually holds — should always come back empty |
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.1.0, live on PyPI. 58 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).
License
MIT
