safe-postgres-mcp

The safe default for giving an AI agent your Postgres. A zero-config, read-only PostgreSQL MCP server where read-only isn't a regex you hope holds — it's enforced by Postgres itself. Every query runs inside a BEGIN TRANSACTION READ ONLY with a statement timeout and a row cap. One npx command: your agent can explore a schema and run SELECTs, but it physically cannot write, cannot stack a second statement, and a runaway query is cancelled within the statement timeout (default 5s) so it can't hang your database.

---

Why another Postgres MCP server?

Most "read-only" database tools enforce read-only by scanning the SQL text for scary keywords. That is a filter, and filters get bypassed. As of early 2026, the original TypeScript reference Postgres MCP server (@modelcontextprotocol/server-postgres) took exactly this text-filter approach and has since been archived in the modelcontextprotocol/servers repo, moved to the community servers-archived list with no maintained successor. Meanwhile popular DBA-oriented alternatives (e.g. Postgres MCP "Pro" / crystaldba) default to unrestricted read/write — read-only is an opt-in access-mode flag — and ship as a Python/Docker install that is friction for the Node/TS majority of MCP users. (Check each project's current docs; the ecosystem moves fast.)

This server inverts that. The guarantee doesn't live in a string matcher — it lives in the database engine.

Defense in depth, from the outside in:

Layer	What it does	Is it the guarantee?
Keyword pre-check	Rejects obvious writes (DELETE FROM …) and stacked statements before a round-trip, with a clear error	No — it's fast-fail UX + a second line
SET LOCAL statement_timeout	Postgres cancels a runaway query instead of hanging your DB	Resource guardrail
BEGIN TRANSACTION READ ONLY	The engine rejects any write (INSERT/UPDATE/DELETE/DDL/…) at execution time	Yes — this is the real guarantee
Row cap + ROLLBACK	Truncates oversized result sets; never commits anything	Resource guardrail

The keyword check is deliberately a courtesy, not the wall. Casing tricks, comment smuggling, or a data-modifying CTE that slips past the text analysis still hit a Postgres READ ONLY transaction and fail with error 25006. Belt and suspenders — and the suspenders are bolted to the engine.

For your outermost layer, point DATABASE_URL at a dedicated least-privilege read-only role (see .env.example). This server is the second wall behind that role, not a replacement for it.

---

60-second quickstart

You need Node >= 20 and a Postgres connection string. Two of the most common clients:

Claude Code

claude mcp add --env DATABASE_URL=postgres://user:pass@host:5432/dbname \
  --transport stdio safe-postgres -- npx -y safe-postgres-mcp

The order matters: keep another flag (--transport stdio) between --env KEY=value and the server name, otherwise the CLI parses the name as another KEY=value pair. Everything after -- is handed to the server untouched.

Verify it's connected:

claude mcp list
claude mcp get safe-postgres

Add --scope project to share it with your team via a checked-in .mcp.json, or --scope user to enable it across all your projects.

Claude Desktop

Open Settings → Developer → Edit Config (or edit the file directly):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "safe-postgres": {
      "command": "npx",
      "args": ["-y", "safe-postgres-mcp"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@host:5432/dbname"
      }
    }
  }
}

Fully quit and reopen Claude Desktop to load it. If it doesn't appear, check ~/Library/Logs/Claude/mcp-server-safe-postgres.log (the server logs all diagnostics to stderr; stdout is reserved for the JSON-RPC channel).

Running from a local build

No npm publish required — build once and point any client at the absolute path:

git clone https://github.com/samuel-cabral/safe-postgres-mcp.git
cd safe-postgres-mcp && npm ci && npm run build

claude mcp add --env DATABASE_URL=postgres://user:pass@host:5432/dbname \
  --transport stdio safe-postgres -- node /abs/path/to/safe-postgres-mcp/build/index.js

The server fails fast: a missing/invalid DATABASE_URL or an unreachable database exits with an actionable message before the agent ever calls a tool.

---

Tools

Five small, curated tools — a focused read-only toolset, deliberately not a 14-tool management suite. Every tool is read-only; nothing here can mutate your data.

Tool	Description	Parameters	Access
query	Run a single read-only SQL statement inside a READ ONLY transaction. A LIMIT is injected if you omit one; returns rows, field types, and a truncated flag.	sql (string, required)	Executes SQL (read-only tx)
explain_query	Return the query plan via EXPLAIN (FORMAT JSON) without running the query (no ANALYZE). Inspect cost/joins/index usage before paying for the query.	sql (string, required)	Plans only, never executes
list_schemas	List all non-system schemas with their owner.	—	Catalog read
list_tables	List tables, views, and materialized views in a schema with approximate row counts (from planner stats — fast, no full scan) and on-disk size.	schema (string, default public)	Catalog read
describe_table	Full description of one table/view: columns (type, nullability, default), primary key, foreign keys, and indexes.	table (string, required), schema (string, default public)	Catalog read

Introspection tools query the Postgres system catalogs with parameterized lookups — identifiers are never string-interpolated into SQL. Every tool returns both human-readable text and typed structuredContent matching its output schema, so an agent can consume either.

---

Safety model

Each row is a thing an agent (or a hostile prompt steering one) could try, and the mechanism that stops it.

Threat	Mitigation
Write / DDL — INSERT, UPDATE, DELETE, DROP, TRUNCATE, GRANT, …	Rejected by the READ ONLY transaction at execution time (Postgres 25006); also fast-failed by the keyword pre-check
Stacked-query injection — SELECT 1; DROP TABLE users	Statement splitter (literal/comment/dollar-quote aware) rejects any input with more than one statement
Data-modifying CTE — WITH x AS (DELETE … RETURNING *) SELECT …	Dedicated hidden-write scan of CTE bodies, backstopped by the READ ONLY transaction
Comment / casing smuggling — /* SELECT */ DELETE …	Comments stripped (respecting string and dollar-quoted literals) before the head check; real enforcement is in the engine, not the text
Runaway query hanging the DB — SELECT pg_sleep(3600)	statement_timeout (per-transaction SET LOCAL, applied inside the tx, + pool-level default) cancels it; default 5s
Oversized result set blowing up memory / agent context	The result is streamed through a server-side cursor that stops at maxRows + 1 rows, so node-pg never buffers more than the cap — even if the query carries its own larger LIMIT. Excess is truncated and truncated: true is returned; default 500 rows
Accidental persistence	Every transaction ends in ROLLBACK — the server never commits
Identifier injection via introspection	System-catalog lookups are parameterized; no identifier interpolation
Disabling a guardrail via a bad env var	Config is validated with hard ceilings (MAX_ROWS ≤ 10,000, QUERY_TIMEOUT_MS ≤ 120,000ms); garbage values refuse to start rather than silently weakening a limit

What this does not do: it does not mask or redact PII in rows you are allowed to SELECT, and it does not substitute for database-level permissions. Grant the connecting role only what the agent should ever see; this server enforces read-only and bounded, not authorized.

---

Configuration

All configuration is environment variables — that's the whole point of zero-config. See .env.example.

Variable	Required	Default	Max	Description
DATABASE_URL	Yes	—	—	Postgres connection string. Point it at a least-privilege read-only role.
POSTGRES_URL	—	—	—	Fallback used only when DATABASE_URL is unset.
QUERY_TIMEOUT_MS	No	5000	120000	Per-statement timeout in ms. A slow query is cancelled, not run forever.
MAX_ROWS	No	500	10000	Hard cap on rows returned by query. Excess rows are truncated and flagged.

---

When to use this vs. alternatives

• Use this when you want an agent to safely read a plain Postgres — RDS, Neon, Supabase-as-plain-PG, or self-hosted — with a READ ONLY guarantee enforced by the database, installed with one npx command and no YAML, no Docker, no Go binary.
• Reach for a DBA-oriented tool (index tuning, health checks, hypothetical indexes) when you're doing performance engineering rather than agent-safe reads — and you're comfortable running it write-enabled.
• Reach for a cloud-vendor server when you're fully inside that vendor's ecosystem (its auth, storage, and edge functions) and don't need neutral, portable Postgres access.

---

Development

npm ci
npm run build       # tsc -> build/, chmod +x the bin
npm run typecheck   # strict TS, no emit
npm test            # vitest run

The suite runs 124 unit + MCP wiring tests with zero external dependencies. Safety parsing (comment stripping, statement splitting, literal-aware CTE-write detection, LIMIT/FETCH row-cap logic, dollar-quote tags) is exercised directly, and the MCP layer is tested end-to-end over an in-memory client/server transport — rejection paths run fully without a live database, because the safety check fires before the connection pool is ever touched.

A further 10 integration tests run against a real Postgres and are skipped automatically unless a DB is provided:

DATABASE_URL=postgres://user:pass@localhost:5432/db npm test

They only issue read-only queries, so a read-only replica is a perfectly safe target. CI (GitHub Actions) type-checks, builds, and tests on Node 20, 22, and 24 for every push and PR.

Built on the official @modelcontextprotocol/sdk (STDIO transport, protocol 2025-06-18) and pg. Written in strict TypeScript.

---

About

Built by Samuel Cabral — senior full-stack engineer (Node.js · TypeScript · NestJS · React · PostgreSQL). I build MCP servers and Claude Code / agent integrations, with a bias toward safety, tests, and tooling that a team can trust in production.

Available for MCP and Claude Code integration work.

• GitHub: github.com/samuel-cabral
• Email: samuelcabral.mail@gmail.com

Licensed under MIT.