Postgres MCP Server (Postgres MCP Pro)

What is Postgres MCP Server (Postgres MCP Pro)?

Postgres MCP Pro is an open-source postgres mcp server from Crystal DBA that gives AI agents safe SQL execution, schema intelligence, EXPLAIN plans, database health checks and index tuning for PostgreSQL.

It does more than wrap a database connection. Alongside running queries, it adds deterministic tools for performance work: it finds slow queries with pg_stat_statements, simulates hypothetical indexes with hypopg, and searches for an index configuration that suits your workload. A restricted, read-only access mode makes it usable against production databases. It is MIT-licensed, published on PyPI as postgres-mcp and on Docker Hub as crystaldba/postgres-mcp, and supports both stdio and SSE transports.

How to use Postgres MCP Server (Postgres MCP Pro)?

Prerequisites: a PostgreSQL connection URI (check it first with psql or pgAdmin) and either Docker or Python 3.12+. The maintainers generally recommend Docker, because Python installs can hit more environment-specific issues.

Install one way:

docker pull crystaldba/postgres-mcp
# or
pipx install postgres-mcp
# or
uv pip install postgres-mcp

Choose an access mode: --access-mode=unrestricted allows full read/write access to data and schema (for development); --access-mode=restricted limits the agent to read-only transactions and caps execution time (for production).

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%/Claude/claude_desktop_config.json). With Docker:

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

The Docker image remaps localhost automatically (host.docker.internal on macOS/Windows, 172.17.0.1 or the right host address on Linux). With uvx instead:

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

If you installed with pipx, use "command": "postgres-mcp"; with uv, use "command": "uv" and "args": ["run", "postgres-mcp", "--access-mode=unrestricted"].

Claude Code

Add the same stdio command with the Claude Code CLI:

claude mcp add postgres \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  -- uvx postgres-mcp --access-mode=restricted

Cursor

Open Cursor Settings from the Command Palette, go to the MCP tab and paste one of the mcpServers blocks above. Windsurf (Open Windsurf Settings Page), Goose (goose configure → Add Extension) and Qodo Gen use the same configuration.

SSE transport (shared or remote server)

Start the server with --transport=sse:

docker run -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

Then point Cursor (mcp.json) or Cline at it with {"type": "sse", "url": "http://localhost:8000/sse"}. Windsurf uses serverUrl instead of url.

Optional extensions

For index tuning and workload analysis, enable pg_stat_statements and hypopg. On managed services such as AWS RDS, Azure or Google Cloud SQL they are usually available already:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

Key features of Postgres MCP Server (Postgres MCP Pro)

• Database health checks: index health (duplicate, unused, invalid), connection utilization, buffer cache hit rates, vacuum health, sequence limits, constraint validation and replication lag.
• Index tuning based on a version of Microsoft's Anytime algorithm, exploring many candidate indexes and weighing performance gains against storage cost.
• EXPLAIN plans, including simulations of hypothetical indexes before you create them.
• Schema intelligence for context-aware SQL generation.
• Safe SQL execution with restricted (read-only) and unrestricted access modes and safe SQL parsing.
• Everything exposed as MCP tools rather than resources, for broad client support.
• stdio and SSE transports; Docker and Python installs.

Postgres MCP Server (Postgres MCP Pro) tools

• Schema exploration: list_schemas, list_objects (tables, views, sequences, extensions) and get_object_details (columns, constraints, indexes).
• Query execution: execute_sql, read-only when the server runs in restricted mode.
• Query planning: explain_query returns the execution plan and can include hypothetical indexes.
• Performance analysis: get_top_queries reports the slowest queries from pg_stat_statements; analyze_workload_indexes recommends indexes for the whole workload; analyze_query_indexes does the same for up to 10 specific queries.
• Health: analyze_db_health runs the full set of health checks.

Use cases of Postgres MCP Server (Postgres MCP Pro)

• Health check: "Check the health of my database and identify any issues."
• Slow query hunt: "What are the slowest queries in my database? And how can I speed them up?"
• Index recommendations: "Analyze my database workload and suggest indexes to improve performance."
• Query optimization: "Help me optimize this query: SELECT * FROM orders JOIN customers ON ..."
• ORM performance fixes in the editor: the project's demo uses Cursor to fix slow SQLAlchemy queries in a generated app.
• Schema-aware development: explore an unfamiliar schema and generate SQL that matches it.

Postgres MCP Server (Postgres MCP Pro) vs alternatives

• Reference PostgreSQL MCP server: the original Model Context Protocol reference server, now in the archived servers repo. It exposes schema as MCP resources and runs read-only queries only. Postgres MCP Pro uses tools and adds health checks, EXPLAIN analysis and index tuning.
• Supabase MCP Server: provides Supabase management features for Supabase projects, rather than generic PostgreSQL performance tuning.
• Other community postgresql mcp servers (several share the postgres-mcp name) mainly run queries and list tables. Check the package and author before installing.

Troubleshooting Postgres MCP Server (Postgres MCP Pro)

• Cannot connect from Docker to a local database: the image remaps localhost, but confirm the URI works with psql from the host first, and that Postgres accepts connections from the Docker network.
• Index tuning or top-queries tools fail: install pg_stat_statements and hypopg. On self-managed Postgres, pg_stat_statements must be listed in shared_preload_libraries, and hypopg may need a system package.
• Writes are rejected: the server is in restricted mode. Switch to --access-mode=unrestricted only in development.
• Python install errors: Python 3.12+ is required; try the Docker image instead.
• SSE client cannot connect: make sure the container publishes the port (-p 8000:8000) and that the client uses /sse; Windsurf needs serverUrl.