pg-mcp-guard
Allows an LLM agent to run read-only SQL queries against PostgreSQL, with safety enforced through database roles, row-level security, query validation, execution limits, and audit logging.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
pg-mcp-guard
Demo video: the real server driven by a real MCP client: RLS, column grants, the COMMIT; DROP attack, a prompt-injection row and the audit log.

An MCP server that lets an LLM agent run read-only SQL against PostgreSQL, where safety is enforced by the database first and by a SQL validator second, never by the prompt. The tests prove that a model can only read rows and columns its principal may read, cannot change anything, cannot exhaust the database, and is audited, even when the validator is switched off.
Why
The archived reference Postgres MCP server ran model-written SQL inside a READ ONLY transaction,
and a multi-statement string (COMMIT; DROP ...) escaped it. See Datadog Security Labs, "MCP
vulnerability case study: SQL injection in the PostgreSQL MCP server". A read-only transaction, or
a filter on the SQL text, is one layer. This repo shows a layered fix, and tests each layer on its
own.
Related MCP server: Safe DB Gateway
How it works
flowchart TD
C["MCP client (the model)"] -->|"stdio, or HTTP with a bearer JWT per request"| T["Transport and auth<br/>principal from a verified token, never from tool arguments"]
T --> G["ToolCallGuard<br/>token expiry, strict arguments, audited refusals"]
G --> V["Validator (pglast, Postgres's own parser)<br/>one SELECT, deny-by-default allowlists"]
V --> E["Executor<br/>READ ONLY transaction, signed context, SET LOCAL limits,<br/>deadline and cancel, bounded fetch"]
E -->|"as mcp_reader"| P[("Postgres<br/>least-privilege role, column grants, forced RLS,<br/>revoked functions, role limits")]
E -->|"as mcp_auditor, fail closed"| A[("audit.tool_calls")]One run_query call:
sequenceDiagram
autonumber
participant M as Model via MCP client
participant S as Server: guard and validator
participant X as Executor
participant DB as Postgres as mcp_reader
participant AU as Audit as mcp_auditor
M->>S: tools/call run_query(sql)
S->>S: principal from the token, check expiry and arguments
S->>S: validate(sql) in a worker thread
S->>X: run_query(principal, sql)
X->>DB: BEGIN READ ONLY, then SET LOCAL limits
X->>DB: SELECT ctx.set_context($1) with an HMAC-signed, short-lived token
X->>DB: DECLARE cursor FOR sql, FETCH at most max_rows + 1
DB-->>X: only rows RLS allows (signature, expiry and membership checked in the DB)
X->>DB: ROLLBACK
X->>AU: INSERT one audit row
AU-->>X: ok, or no result is returned
X-->>S: rows, or an exact reason such as function_not_allowed
S-->>M: result fenced and labelled as untrusted dataDefence in depth
Layer | What it stops | Proof |
Postgres role and grants | writes, DDL, catalog and audit reads, | tests/db/test_grants.py, tests/db/test_set_config.py (validator off) |
Row-level security + signed context | another tenant's rows; forged, tampered or expired contexts; non-members | tests/db/test_rls.py (validator off) |
Role limits | long queries, lock waits, huge spilling sorts, connection floods | tests/db/test_limits.py (validator off) |
Validator | anything but one | tests/validator/ (adversarial corpus) |
Executor | multi-statement strings, unbounded results, queries past the deadline, state left for the next caller, unaudited calls | tests/executor/ (many with the validator off) |
Transport and auth | identity from tool arguments, bad or expired tokens, session-id reuse, DNS rebinding, oversized bodies, tokens in logs |
The full attack → control → test table, with residual risks, is in the threat model.
Why many tests run with the validator disabled
This is deliberate. A validator is code, and code has bugs. The claim this project makes is that the database holds even when the validator lets something through. So the database tests connect as the real runtime role and send attacks straight to Postgres, and many executor and HTTP tests replace the validator with one that allows everything. The validator has its own corpus of attacks with expected verdicts, and a meta-test fails if a database attack test has no matching corpus entry.
Quickstart
Needs Docker and uv.
uv run python scripts/dev_setup.py # .env with fresh secrets, Postgres, migrations, demo data
uv run python scripts/demo.py # the real server, driven by a real MCP clientdev_setup.pycreates.envonly if it does not exist, and never prints secrets. If port 5432 is taken, use--port 5433.demo.pyshows each scene's question, the SQL and the outcome, and exits non-zero if any scene misbehaves.--pausewaits for Enter between scenes (for recording);--no-colorgives plain output.
To connect Claude Desktop, Claude Code or MCP Inspector (stdio or HTTP), see docs/clients.md.
Development
uv run pytest # migrates and seeds its own mcpguard_test database
uv run ruff check . && uv run ruff format --check . && uv run mypy app
uv run python -m scripts.mint_token --user alice --tenant acme --ttl 1h # dev only
MCP_PRINCIPAL_TOKEN=<token> uv run python -m app.server # stdio
uv run python -m app.server --transport http # 127.0.0.1:8765/mcpDesign decisions are recorded in docs/decisions/.
Implemented / Tested
Database layer (ADR 0002):
roles
mcp_migrator,mcp_rls_helper,mcp_reader,mcp_auditor;forced RLS keyed to an HMAC-signed context verified in Postgres;
column grants and
security_invokerviews;role-level limits;
revoked
set_config, stats, cancel and large-object functions;an append-only audit table.
Validator (ADR 0003): pglast at Postgres 18.6, deny by default, adversarial corpus. Every allowed query is also run against the real database.
Executor (ADR 0004):
read-only transaction;
server-side cursor over the extended protocol;
byte and row caps;
deadline, cancel and backstop;
DISCARD ALL;mapped errors;
fail-closed audit, including cancellations.
MCP server over stdio (ADR 0005):
three read-only tools with strict inputs;
principal from a verified JWT, expiry checked per call;
untrusted-data fence;
fail-closed startup checks.
Streamable HTTP (ADR 0006):
bearer token on every request through the SDK's auth path, audited 401s;
isolation of principals in one process;
loopback by default, DNS-rebinding protection, body and session limits.
Demo and setup:
scripts/demo.py(checked in CI),scripts/dev_setup.py.
Planned
Record the demo video (shot list).
An asymmetric token verifier (OIDC / JWKS) as an alternative to the HS256 shared secret.
Limitations
Exfiltration by the client: the server limits what a principal can read, not what the MCP client does with it afterwards.
HS256 shared secret: in stdio mode the operator can mint any identity.
No TLS: use a reverse proxy for anything beyond loopback.
More, with the reasoning, in the threat model.
How this was built
I built this with Claude Code, working from my own specification (CLAUDE.md) one phase at a time. Each phase started as a plan that I reviewed, amended and approved before any code was written. I then reviewed the output and the real test runs, and pushed back with changes where needed; several of the security fixes came out of that review. I can explain every design decision in this repository, and the reasoning is written down in the ADRs.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Security layer for AI agents: Retrieve for controlled SQL reads, Guard for allow/deny writes.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to safely query PostgreSQL by intercepting and auditing every generated SQL statement before it reaches the database, blocking destructive commands like DROP/TRUNCATE, unbounded DELETE/UPDATE statements, stacked queries, and SQL injection probes. It exposes tools for validating query safety and enforcing a strict read-only (SELECT/EXPLAIN) policy.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to query PostgreSQL databases securely with read-only defaults, PII masking, rate limiting, and human-approved, expiring mutation tokens.91Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query a Postgres database read-only through a policy layer rather than a raw connection string. Enforces table and column allowlists, row limits, mandatory predicates, PII masking and append-only audit logging, while refusing writes, joins, subqueries and unlisted functions.MIT
- AlicenseNot gradedqualityBmaintenanceGives AI agents read-only access to Postgres with parser-checked queries, hidden tables and columns, row limits and timeouts, caller-bound Row-Level Security, and a tamper-evident audit log.MIT