PostgreSQL MCP Server — Claude Code MCP server: query your database
Gives an agent access to PostgreSQL: queries, schema introspection, EXPLAIN plans and health checks. Read-only unless you opt in.
claude mcp add postgres-mcp -- npx -y @yawlabs/postgres-mcpWhat PostgreSQL MCP Server does
The server connects through DATABASE_URL and exposes a set of tools: pg_query for SQL, pg_list_schemas, pg_list_tables and pg_describe_table for schema work, pg_explain for plans, plus pg_top_queries, pg_seq_scan_tables, pg_unused_indexes, pg_table_bloat and pg_inspect_locks for diagnostics. User SQL goes out over the extended query protocol, so each request carries a single statement. Bind values are passed as a params array for $1, $2 and so on.
Writes stay off until you set ALLOW_WRITES=1. A separate tool, pg_readonly, never leaves read-only mode no matter what that variable says, which suits hosts that gate tools one by one. The recommended setup is a least-privileged Postgres role, since the database then enforces the boundary itself. Running pg_explain with analyze: true on a non-SELECT needs ALLOW_WRITES=1 and rolls back afterwards, though a sequence the statement advanced stays advanced.
Version 0.12 brought pg_index_advisor, which costs candidate indexes with HypoPG hypothetical indexes and creates nothing on disk. Audit logging of SQL is off by default and never records bound parameter values. Node 22 or newer is required. On 0.12.0, upgrade: in pg_index_advisor SQL passed through the statements argument could run outside the read-only transaction, and hosts often auto-allow that tool because it carries a read-only annotation.
What it helps with
- read someone else's schema without hand-writing
pg_catalogjoins - see a query plan and find where it slows down
- spot sequential scans and indexes nothing uses
- work out which session is holding a lock
- hand an agent database access without risking dropped tables
Example prompts for the agent
- List the tables in the
publicschema and describeorders - Run EXPLAIN with analyze on
SELECT * FROM orders WHERE user_id = $1 - Which indexes would help this query?
How to install PostgreSQL MCP Server
Platform CLI
claude mcp add postgres-mcp -- npx -y @yawlabs/postgres-mcpPlatform CLI
codex mcp add yawlabs-postgresql-mcp-server -- npx -y @yawlabs/postgres-mcpConfig file
{
"mcpServers": {
"yawlabs-postgresql-mcp-server": {
"command": "npx",
"args": [
"-y",
"@yawlabs/postgres-mcp"
]
}
}
}Config file
{
"servers": {
"yawlabs-postgresql-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@yawlabs/postgres-mcp"
]
}
}
}Platform CLI
gemini mcp add yawlabs-postgresql-mcp-server npx -y @yawlabs/postgres-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about PostgreSQL MCP Server
How do I install PostgreSQL MCP Server in Claude Code?
Run claude mcp add postgres-mcp -- npx -y @yawlabs/postgres-mcp. Then set your connection string in DATABASE_URL.
What does PostgreSQL MCP Server do?
It gives an agent tools to query PostgreSQL, inspect schemas, read EXPLAIN plans and check performance. Writes only happen when ALLOW_WRITES=1 is set.
How is it different from @modelcontextprotocol/server-postgres?
That package is archived and unmaintained, and it still carries a documented stacked-query injection. Here user SQL travels over the extended query protocol, so extra statements get rejected.
