How to Set Up a PostgreSQL MCP Server for Claude, Cursor & Codex

This post was written by an engineer at QueryPlane. QueryPlane is an app builder for your database: bring your own postgres db and you can create interactive applications to share with other developers, coworkers or even your customers. If you’re interested in trying it out, get started here.

---

MCP (Model Context Protocol) lets AI tools like Claude Desktop, Claude Code, Cursor, and Codex connect directly to your PostgreSQL database. Instead of copy-pasting schemas and query results into chat, the AI can inspect your tables, run queries, and analyze your data autonomously.

In this post, we’ll cover:

• What is MCP — How the protocol works
• Best Postgres MCP servers — Comparing the top options
• Setup guides — Step-by-step for Claude Desktop and Claude Code
• Security considerations — Keeping your database safe

What is MCP?

The Model Context Protocol is an open standard created by Anthropic that lets AI applications connect to external data sources and tools. Think of it as a USB-C port for AI — a standardized way for any AI client to talk to any data source.

For databases, MCP servers expose tools like list_tables, describe_table, and execute_sql that AI agents can call. This means Claude can explore your schema, write queries based on your actual table structure, and validate results — all without you manually providing context.

Best PostgreSQL MCP Servers

1. Postgres MCP Pro (CrystalDBA)

postgres-mcp is the most feature-rich Postgres MCP server available (~2,600 stars). It goes beyond basic querying to include performance analysis and index tuning.

Features:

• Configurable read/write access
• Performance analysis with EXPLAIN plans
• Index tuning recommendations (uses the Anytime Algorithm)
• Health checks (buffer cache, vacuum status)
• Hypothetical index support via hypopg

Claude Desktop config (via Docker):

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://user:pass@host:5432/mydb"
      }
    }
  }
}

2. Anthropic Reference Server (@modelcontextprotocol/server-postgres)

The reference implementation from Anthropic (now archived, but still functional). Lightweight and read-only — good for getting started quickly.

Features:

• Schema inspection (list tables, describe columns)
• Read-only query execution
• Minimal setup via npx

Claude Desktop config:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:pass@localhost:5432/mydb"
      ]
    }
  }
}

Claude Code setup:

claude mcp add --transport stdio postgres-db -- \
  npx -y @modelcontextprotocol/server-postgres \
  postgresql://user:pass@localhost:5432/mydb

3. DBHub (Bytebase)

DBHub is a multi-database MCP server (~2,600 stars) that supports PostgreSQL, MySQL, SQL Server, MariaDB, and SQLite with a single install.

Features:

• Zero dependencies — runs via npx
• Token-efficient (only 2 MCP tools to maximize AI context window)
• Built-in web UI for testing
• Read-only mode

Claude Code setup:

claude mcp add --transport stdio dbhub -- \
  npx @bytebase/dbhub@latest \
  --transport stdio \
  --dsn "postgres://user:pass@localhost:5432/mydb"

4. pgmcp

pgmcp (~530 stars) converts natural language to SQL queries and supports multiple output formats.

Features:

• Natural language to SQL conversion
• Free-text search across all columns
• Automatic streaming for large results
• Multiple output formats (table, JSON, CSV)

Which Postgres MCP Server Should You Use?

Server	Stars	Read-only	Write	Performance analysis	Multi-database
Postgres MCP Pro	~2,600	Yes	Configurable	Yes	No
Official Anthropic	~84,000*	Yes	No	No	No
DBHub	~2,600	Yes	No	No	Yes
pgmcp	~530	Yes	No	No	No

Stars for entire modelcontextprotocol/servers repo

For most developers, start with the official Anthropic server — it’s the simplest to set up and covers schema exploration and read queries. If you need performance tuning capabilities, upgrade to Postgres MCP Pro. If you work with multiple databases, use DBHub.

Security Considerations

Connecting an AI agent to your database carries risk. Follow these practices:

• Use a read-only database user — create a dedicated role with SELECT-only permissions
• Connect to a replica — point MCP at a read replica, not your primary
• Limit schema access — restrict the user to specific schemas with GRANT USAGE
• Don’t expose credentials in configs — use environment variables for connection strings
• Audit query logs — enable log_statement = 'all' on the connected user to track what the AI runs

-- Create a read-only user for MCP
CREATE USER mcp_reader WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE mydb TO mcp_reader;
GRANT USAGE ON SCHEMA public TO mcp_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO mcp_reader;

Using MCP with QueryPlane

If you want the benefits of AI-powered database access without managing MCP servers, QueryPlane provides this out of the box. Connect your PostgreSQL database and use AI to generate queries, explore schemas, and build dashboards — all from your browser with built-in access controls and team collaboration.

QueryPlane handles the security layer for you: role-based access, read-only modes, query auditing, and team permissions — without configuring MCP servers or worrying about credential management.

FAQ

What is a Postgres MCP server?

A Postgres MCP server is a process that implements the Model Context Protocol to let AI tools (Claude, Cursor, Codex, Windsurf) connect to your PostgreSQL database. It exposes tools for listing tables, describing schemas, and running SQL queries.

How do I connect Claude to PostgreSQL?

Install an MCP server like @modelcontextprotocol/server-postgres via npx, then add it to your Claude Desktop config or use claude mcp add in Claude Code. The AI can then query your database directly.

Is it safe to connect AI to my database?

It can be safe with proper precautions: use a read-only database user, connect to a replica, limit schema access, and audit queries. Never give an MCP server write access to a production database without careful access controls.

Does MCP work with managed PostgreSQL (RDS, Cloud SQL, Supabase)?

Yes. MCP servers connect via standard PostgreSQL connection strings. Any managed provider that allows external connections (AWS RDS, Google Cloud SQL, Azure Database, Supabase, Neon, PlanetScale) works with MCP.

Wrapping up

MCP makes it easy to give AI agents direct access to your PostgreSQL data. The ecosystem is maturing quickly — from Anthropic’s official reference server to feature-rich options like Postgres MCP Pro. Start with a read-only setup, see how it fits your workflow, and scale up from there.