postgres-mcp

A production-ready MCP server for PostgreSQL — built for Claude Desktop, Claude Code, and any MCP-compatible AI agent.

Extends crystaldba/postgres-mcp with:

• Aurora IAM auth — connect to AWS Aurora Postgres without embedding passwords

• Playbook mode — chain diagnostic tools into named runbooks Claude executes end-to-end

• Pre-packaged Claude Desktop config — one paste and you're connected

• rajivonai brand config — opinionated defaults that pair with pg-advisor and easy-pg-lab

Claude → postgres-mcp → your Postgres (local, RDS, or Aurora)

What this MCP server can do

What it does NOT do by default:

• No INSERT / UPDATE / DELETE / DDL (read-only mode is the default)

• No cross-database access (scoped to the configured database)

• No credential storage (uses env vars or IAM)

You can enable write access with --allow-writes — but for production, read-only is recommended.

Related MCP server: Database MCP Server

What crystaldba/postgres-mcp already provides (and we inherit)

This project builds on crystaldba/postgres-mcp. Credit to the crystaldba team for:

• Real cost-based index simulation using the Anytime Algorithm

• EXPLAIN plan analysis and bottleneck identification

• Built-in health checks (buffer cache, vacuum, sequences, replication)

• Configurable read/write access controls

We do not fork or modify their core engine — we wrap it and add the layers described above. If a feature request belongs in the core, we'll upstream it.

Install

pip install postgres-mcp
# or from source:
git clone https://github.com/rajivonai/postgres-mcp && cd postgres-mcp
pip install -e .

Requires Python 3.11+.

Quick start

Standard Postgres (local or RDS password auth)

postgres-mcp serve \
  --host localhost \
  --port 5432 \
  --user postgres \
  --dbname mydb

Or via connection string:

postgres-mcp serve --url "postgresql://user:pass@host:5432/mydb"

Aurora Postgres with IAM auth (no password needed)

postgres-mcp serve \
  --aurora-host my-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com \
  --aurora-region us-east-1 \
  --aurora-user myuser \
  --dbname mydb

Requires the AmazonRDSReadOnlyAccess IAM policy (or equivalent) on the calling role.

Claude Desktop setup

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "postgres-mcp",
      "args": [
        "serve",
        "--url", "postgresql://postgres:postgres@localhost:5432/mydb"
      ]
    }
  }
}

For Aurora (uses AWS profile default):

{
  "mcpServers": {
    "postgres-aurora": {
      "command": "postgres-mcp",
      "args": [
        "serve",
        "--aurora-host", "my-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com",
        "--aurora-region", "us-east-1",
        "--aurora-user", "myuser",
        "--dbname", "mydb"
      ]
    }
  }
}

Restart Claude Desktop after editing.

Claude Code setup

# Add to your project's .claude/mcp.json
{
  "servers": {
    "postgres": {
      "command": "postgres-mcp",
      "args": ["serve", "--url", "${PG_URL}"]
    }
  }
}

Or run inline:

claude --mcp-server "postgres-mcp serve --url $PG_URL"

Playbooks

Playbooks are named diagnostic sequences — Claude executes a structured workflow rather than ad-hoc tool calls. Run them from the CLI:

postgres-mcp playbook slow-query --url "$PG_URL" --threshold-ms 500
postgres-mcp playbook pre-deploy  --url "$PG_URL"
postgres-mcp playbook health      --url "$PG_URL"
postgres-mcp playbook replica-lag --url "$PG_URL"

Or ask Claude directly (once the MCP server is running):

"Run the slow-query playbook on my database"

Available playbooks

Security model

The server never executes statements outside the configured access level. All tool calls are logged to stderr.

Part of the rajivonai polyglot database toolkit

rajivonai.com · easy-pg-lab · pg-advisor · skills