Setup

Add it to your MCP client. Node.js 20 or later.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@contextflo/postgres-mcp", "postgresql://localhost/mydb"]
    }
  }
}

Loading code sample...

Claude Code: run

claude mcp add postgres -- npx -y @contextflo/postgres-mcp postgresql://localhost/mydb

Loading code sample...

Cursor: .cursor/mcp.json, same shape.
Claude Desktop: claude_desktop_config.json in ~/Library/Application Support/Claude/ (macOS) or %APPDATA%\Claude\ (Windows).
VS Code: .vscode/mcp.json, with servers in place of mcpServers.

Then generate a context file:

npx @contextflo/postgres-mcp init postgresql://localhost/mydb

Loading code sample...

That writes .contextflo/context.md, seeded from your COMMENT ON values, and prints the CREATE ROLE snippet for a read-only role.

Tools

Tool	What it does
`query`	Runs one read-only statement: SELECT, WITH ... SELECT, EXPLAIN, or SHOW.
`list_tables`	Lists readable tables with descriptions. pattern matches anywhere in the name or description.
`get_table_context`	Columns, types, keys, foreign key targets, enum values, curated descriptions.
`add_table_context`	Lets the agent note a gotcha it found (amount is in cents) in the context file.

Read-only, four layers

Each layer stops the archived server's exploit on its own.

Extended query protocol. Postgres itself rejects multi-statement input.
Read-only connection. Every statement runs in BEGIN READ ONLY and always ends in ROLLBACK.
The real Postgres parser. The whole parse tree is walked, so a write hidden in a CTE is caught.
A read-only role. Enforced by Postgres regardless of the code above.

The known exploit, sent to this server:

# query tool input
{"sql": "COMMIT; DROP SCHEMA public CASCADE"}

# returned as a tool error, nothing runs
Only one statement per call is allowed; received 2. Send each statement as a separate query call.

Loading code sample...

Not covered: a user-defined function called from a SELECT can do whatever its body does, which is why the read-only role is the recommended setup. And read-only is not confidentiality: the model can read anything the role can.

Migrating from `@modelcontextprotocol/server-postgres`

The reference server was archived in May 2025 and deprecated on npm on July 10, 2025, yet it was still downloaded about 105,000 times in the week of September 19 to 25, 2026. Swap the package name. The tool is still query, still takes sql. Deliberate differences:

Multi-statement SQL and SET/RESET are rejected with a clear error.
Results are capped at 1000 rows and 50,000 characters by default. Truncation is always stated.
Schema discovery is a tool, not just a resource.
All non-system schemas are visible, not only public.

The context file

Seeded from your existing COMMENT ON values, edited by you, and appended to by the agent when it finds a gotcha. Keep it in git and review the diff.

# Database context

Revenue means gross, before refunds.
"Active customer" means an order in the last 90 days.

## Tables

### public.orders
One row per customer order. Source of truth for revenue, not `orders_legacy`.

- revenue_usd: Gross revenue, before refunds. Net lives in `order_refunds`.
- status: One of pending, paid, refunded.

Loading code sample...

Everything above ## Tables is handed to the model. Your text wins over COMMENT ON, and edits apply on the next tool call with no restart.

Options

--max-rows <n>            Maximum rows returned per query (default: 1000)
--max-output-chars <n>    Character budget for one query result (default: 50000)
--statement-timeout <ms>  Server-side statement timeout (default: 30000)
--context-file <path>     Curated schema context (default: .contextflo/context.md)
--no-context-writes       Do not offer add_table_context; the context file is only read
--log-file <path>         Query audit log (default: .contextflo/log.md once that directory exists)
--no-log                  Never write a query log
--http                    Serve over streamable HTTP instead of stdio
--port <n>                HTTP port (default: 8080)
--host <addr>             HTTP bind address (default: 127.0.0.1)

Loading code sample...

DATABASE_URL supplies the connection string if you do not pass one.

Using it with a team? Contextflo adds shared definitions, per-person access control and an audit trail. Try Contextflo

A Postgres MCP server that stays read-only