Postgres MCP Server

Let Claude Code, Claude Desktop, Cursor or any MCP client explore and query a PostgreSQL database, and review its performance, without being able to change it.

• Read-only by design. Every query runs inside BEGIN READ ONLY with statement_timeout, lock_timeout and a row cap, then rolls back. A statement checker refuses writes, multiple statements, COPY, DO, SET, data-modifying CTEs and functions that read server files or signal other sessions, before anything reaches the server.
• Knows your schema. Tables with estimated rows and sizes, columns with defaults and comments, primary/foreign keys in both directions, check constraints, indexes with their scan counts, view SQL, sample rows.
• Finds slow spots. explain_query turns a plan into findings (full scans, disk sorts, bad estimates). db_health lists unused indexes, foreign keys without an index, tables without a primary key, dead rows, never-analyzed tables, long-running queries. top_queries reads pg_stat_statements.
• Works with PostgreSQL 13+ over a standard connection string (tested on PostgreSQL 14 and 18). Hosted Postgres (Supabase, Neon, RDS, Cloud SQL ...) connects the same way.

Python 3.9+ and psycopg 3:

python3 -m pip install "psycopg[binary]"      # or: python3 -m pip install -r requirements.txt

Create a read-only user (recommended; see examples/read_only_role.sql):

CREATE ROLE mcp_reader LOGIN PASSWORD 'change-me';
ALTER ROLE mcp_reader SET default_transaction_read_only = on;
GRANT pg_read_all_data TO mcp_reader;    -- PostgreSQL 14+
GRANT pg_read_all_stats TO mcp_reader;   -- optional: other sessions in db_health / top_queries

If your host doesn't let you grant pg_read_all_data, use the per-schema GRANT SELECT lines in the same file. Claude Code

claude mcp add postgres -- python3 /path/to/postgres-mcp-server/server.py --dsn postgresql://mcp_reader:PASSWORD@localhost:5432/mydb

Or install the folder as a plugin (.claude-plugin/plugin.json, .mcp.json, skill postgres-analyst) and set PGMCP_DSN in your environment.

Claude Desktop / Cursor: copy examples/configs/claude_desktop_config.json or examples/configs/cursor-mcp.json and fill in the path and connection string. Several databases: repeat --dsn name=postgresql://... (or separate them with spaces in PGMCP_DSN). With no DSN the standard PGHOST, PGDATABASE, PGUSER, PGPASSWORD variables and ~/.pgpass are used.

Options: --max-rows 200 (cap per query), --timeout 10 (seconds, per statement), --allow-writes (adds write_query; the skill asks before every write).

./run_tests.sh                                             # unit tests, no database needed
PGMCP_TEST_DSN=postgresql://postgres:pw@localhost/scratch ./run_tests.sh   # + integration tests on a real server
PGMCP_DEMO_DSN=postgresql://postgres:pw@localhost/scratch ./demo.sh        # MCP session on a fictional shop

The integration tests and the demo create schema demo_shop in the database you point them at. Use a scratch database.

• The model writes the SQL. Check the query it shows you before acting on a number.
• Read-only means *this server* won't change data. Use a read-only role as well: a superuser can bypass a lot, and the server warns when it is connected as one.
• explain_query with analyze: true really runs the query (inside a read-only transaction, with the timeout).
• db_health counts are since the last statistics reset or restart, on the server you're connected to; check replicas separately before dropping an "unused" index.
• top_queries needs the pg_stat_statements extension.
• Not a migration tool, an ORM or a backup tool.