postgres-mcp-hardened

🚧 Version 0.1.10 — the rest of an outside review, and a fix that was too blunt

Published: binaries for five platforms with checksums, Sigstore signatures and build provenance; .mcpb bundles for one-click install; an image on ghcr.io for amd64 and arm64; a package on npm; and an entry in the official MCP registry.

0.1.8 and 0.1.9 closed six bypasses that four independent reviewers found in 0.1.7, none of them found by us. Two days of our own adversarial work had come back mostly clean the day before. Passing the tests you thought to write is not the same as looking. The one that mattered most needs no privileges at all: with a column redacted, a join on it through USING answered whether a given value was present, which is a complete equality oracle against the least-privilege reader this project tells you to configure.

0.1.10 closes the three findings that were left open. With MCP_ALLOW_SCHEMAS=public, SELECT * FROM secret.salaries was refused while describe_table handed over every column, type and default of that same table. An ordinary connection string carrying no sslmode used the driver's prefer, which sends everything in the clear whenever the server declines TLS, and anyone on the wire can make it decline. And MCP_SSLROOTCERT added a private certificate authority to 242 public ones instead of replacing them, so an operator who believed they had pinned trust to their own issuer had not.

The first version of that TLS fix was wrong in a way worth reading about. It asked "is this loopback" and demanded TLS from everything else, which took down six PostgreSQL version jobs, the conformance run, the container check and the adversarial corpus in a single push. All of them reach the database the way ordinary deployments do: postgres://user:pass@postgres:5432/db, a service name on a private network. Docker Compose and Kubernetes are not the public internet, and a server that demands TLS from a container on a bridge network is a server people switch off entirely. The question is now whether somebody untrusted can sit on the wire, not whether the address is loopback, and a real socket to a PostgreSQL reachable only by service name is in the test suite, because a rule about networks should be tested over a network.

A resource limit is documented and not solved, in THREAT_MODEL.md: 49 bytes of SQL make PostgreSQL fold a constant into 5.9 GB of backend memory during planning, and a five second statement_timeout does not stop it. The obvious shapes are refused; the general problem is upstream of anything this server can do.

Every change here was reproduced against a running server before being fixed, and each is in CHANGELOG.md with the query.

Everything here is 0.1.x because nobody outside this project has run it against their own data.

The official Postgres MCP server was deprecated in 2024 and still gets 391k downloads a month. Its entire defence is one database-level read-only transaction — and that alone does not stop every write. This is a maintained Rust replacement with defence in depth.

A drop-in Model Context Protocol server that lets an AI agent query PostgreSQL — read-only, enforced at the database level, with real SQL validation, timeouts, cost limits, OAuth 2.1, and an audit trail. Speaks Streamable HTTP and stdio, and negotiates the MCP revision: 2026-07-28 (current, and the default since upstream released it on 2026-08-03), 2025-11-25, and 2025-06-18 — what most shipping clients still speak today. A client asks for what it knows; it is not negotiated down.

Try to break it — one command, no database

The read-only guard has an offline mode. Hand it a statement and it says what it decided: no database, no configuration, nothing installed permanently.

npx postgres-mcp-hardened --validate "/* comment */ DROP TABLE users"
# REJECT: non-read-only statement: Drop

npx postgres-mcp-hardened --validate "SELECT 1; DROP TABLE users"
# REJECT: multiple statements are forbidden

npx postgres-mcp-hardened --validate "WITH d AS (DELETE FROM t RETURNING *) SELECT * FROM d"
# REJECT: non-read-only statement: non-read-only query (CTE / SELECT INTO / FOR UPDATE)

npx postgres-mcp-hardened --validate "SELECT * FROM orders WHERE id = 1"
# ALLOW

If something that writes comes back ALLOW, that is the most valuable thing anyone can send us. It needs no working exploit and no write-up — one line of SQL and "this should not be allowed" is a complete report. Anything that gets past the guard goes through SECURITY.md; everything else is an ordinary issue, and the bar for opening one is this looks wrong to me, not I am certain.

The fuzzer is deterministic and prints its seed, so whatever it finds reproduces on a machine that has never seen yours — a million mutations take about a minute:

npx postgres-mcp-hardened --fuzz 1000000
# fuzz: 1000000 iterations, seed 1592594996, slowest validation 8 ms
# RESULT: 0 invariant violations

For the whole thing against a real database, docker compose -f examples/docker-compose.yml up -d brings up PostgreSQL with sample data and the server in front of it, connecting as a role that holds SELECT and nothing else.

Every bypass found so far lives in the MUST_REJECT corpus in src/validate.rs and runs on every commit, recorded with what it cost rather than tidied away. Yours would join them.

Why

@modelcontextprotocol/server-postgres is deprecated on npm (last publish December 2024) and still sees 475,790 downloads in the 30 days to 9 August 2026. Credit where it is due: its approach is not naive — it wraps each query in BEGIN TRANSACTION READ ONLY and always ROLLBACKs, which is a real defence and one this server now adopts as well.

The problem is that it is the only defence, and it is not complete:

• A read-only transaction does not block every write, and a rollback does not undo everything it lets through. Two separate facts, and the second is the one that matters.

  gin_clean_pending_list() runs inside SET TRANSACTION READ ONLY and its work survives the rollback: an index with 25 pending pages has 0 after the transaction is rolled back. pg_backup_start() puts the session into backup state, survives DISCARD ALL, and with the default fast => false waits for a spread checkpoint while forcing full_page_writes on, which is a real cost on a busy server. pg_import_system_collations() also executes without raising SQLSTATE 25006, but be careful how much weight you put on it: that one IS undone by a rollback, so against a server that always rolls back it is a curiosity rather than a bypass.

  Reproduce it, but read the two preconditions first, because without them you will see a zero or an error and conclude we made this up. All three need superuser or ownership of the object. And the import only restores collations that are missing, so something has to be removed first:

  -- as superuser, and note these are three separate transactions: a statement that errors
  -- inside a block aborts the whole block, so they cannot be run as one.
  DELETE FROM pg_collation WHERE oid IN (SELECT oid FROM pg_collation ORDER BY oid DESC LIMIT 200);
  
  BEGIN READ ONLY;
    DELETE FROM pg_collation WHERE collname LIKE 'zu%';  -- ERROR: cannot execute DELETE ...
  ROLLBACK;
  
  BEGIN READ ONLY;
    SELECT pg_import_system_collations('pg_catalog');    -- 200, no error
  COMMIT;                                                -- and now the rows are there
  

  Both are writes, both are inside a read-only transaction, and one is refused while the other is not. That asymmetry is why this server does not treat the transaction as its only defence. It is also why the role matters more than any of this: every example above needs privileges a least-privilege reader does not have, and this server refuses to start as a network listener when the role it was given can write. What it cannot control is which connection string somebody pastes into a client config, and the usual answer is whichever one they already had.

• No statement timeout, no cost guard, no row limit — one query can run until the server gives up.

• No authentication, no audit trail, no handling of prompt injection through returned row data.

• One source file of 143 lines, unmaintained since December 2024, no test suite.

This server keeps the rollback, adds AST validation in front of it, and adds the operational layers the original never had.

postgres-mcp-hardened vs the archived original

| | archived server-postgres | postgres-mcp-hardened | |---|---|---| | Read-only enforcement | BEGIN TRANSACTION READ ONLY + ROLLBACK — one layer, and PostgreSQL lets some writes through it | AST validation (sqlparser) plus the same read-only transaction and rollback, plus a denylist for functions that write despite it | | Multi-statement / DROP via CTE | reaches the database and is stopped only by the transaction | rejected by the parser, before it reaches the database | | Statement timeout | none | statement_timeout + idle_in_transaction_session_timeout enforced | | Runaway / expensive queries | run unbounded | EXPLAIN cost guard rejects them before execution | | Prompt injection via row data | raw output | wrapped trusted="false" + delimiter escaping | | Error messages | leak schema (relation X does not exist) | structured, non-leaking, actionable | | Auth | none | OAuth 2.1 (RS256 JWT, scope + audience + issuer) | | Audit | none | tamper-evident hash-chained log | | Schema as MCP resources | ✅ | ✅ — plus comments, primary and foreign keys | | Tests / CI | none | unit + end-to-end suites against live PostgreSQL, a deterministic fuzz harness, conformance driven by the official MCP SDK, clippy + cargo audit + container build on every push | | Transport | stdio / deprecated SSE | Streamable HTTP + stdio | | Maintained | ❌ deprecated since 2024 | ✅ |

Install

Five ways in, in the order most people want them.

One click, for a client that accepts .mcpb bundles: download postgres-mcp-hardened-<your-platform>.mcpb from the latest release and open it. The bundle asks for the connection string and stores it in the OS keychain rather than in a plain-text config file. Nothing to install, nothing to edit.

Through npm — shortest, and the one your MCP client config can point at directly. There is no Node runtime involved at run time: the package is a launcher that fetches the native binary for your platform and verifies its checksum before running it.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "postgres-mcp-hardened", "--stdio"],
      "env": { "DATABASE_URL": "postgres://readonly_user:PASSWORD@localhost:5432/mydb" }
    }
  }
}

The connection string goes in env, not in args, on purpose: arguments show up in ps output and in shell history on a shared machine, and a database password does not belong there.

A binary from the releases page — one file, nothing to keep up to date, and the option to take if your machine has no Node at all. (Not a static binary, as this page claimed until 0.1.7: the -gnu and macOS targets link the system C library like any other native program. There is simply nothing to install alongside it.) Every release carries builds for Linux, macOS and Windows on x86-64 and arm64, each with a checksum and a signature; verifying them is the next section.

As a container, if that is how you run things. The image is distroless and runs as a non-root user, and the same signatures cover it as cover the binaries.

docker run --rm -p