# PostgreSQL MCP Server

Gives an agent access to PostgreSQL: queries, schema introspection, EXPLAIN plans and health checks. Read-only unless you opt in.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 10
- Author: YawLabs
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/YawLabs/postgres-mcp
- Updated: 2026-10-15
- HTML: https://affpapa.org/en/nevibecode/mcp/yawlabs-postgresql-mcp-server

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add postgres-mcp -- npx -y @yawlabs/postgres-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add yawlabs-postgresql-mcp-server -- npx -y @yawlabs/postgres-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "yawlabs-postgresql-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@yawlabs/postgres-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "yawlabs-postgresql-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@yawlabs/postgres-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add yawlabs-postgresql-mcp-server npx -y @yawlabs/postgres-mcp
```

## When to use it
- read someone else's schema without hand-writing `pg_catalog` joins
- 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
- List the tables in the `public` schema and describe `orders`
- Run EXPLAIN with analyze on `SELECT * FROM orders WHERE user_id = $1`
- Which indexes would help this query?

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89609
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89899
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16730
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40459
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27844
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49863

## Other versions with the same name
- [PostgreSQL MCP Server · neverinfamous](https://affpapa.org/en/nevibecode/mcp/neverinfamous-postgresql-mcp-server.md) — ★ 12

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md