Postgres MCP Server: Setup, Config, Safe SQL (2026)

The Postgres MCP server connects AI assistants to PostgreSQL databases through the Model Context Protocol (MCP). It lets Claude, Cursor, and Claude Code inspect a schema, list tables, review EXPLAIN plans, and run SQL in natural language. It is the highest-demand database server in the MCP ecosystem. It grounds the model in your real schema instead of a guess from training data.

The implementation landscape changed in 2025. Anthropic’s original reference server was deprecated and archived, so the current question is not how to install the Postgres server but which Postgres server to install. This guide answers that first. It then covers the connection string in full, the install for every client, and the read-only safety model a live database demands.

This guide covers what the server exposes, which implementation to install now, the connection string anatomy, setup per client, safe SQL, and what you can build once it is connected.

All database MCP servers · What MCP is and how it works

What Does the Postgres MCP Server Expose?

The Postgres MCP server exposes schema inspection, table and object listing, query execution, and EXPLAIN-plan analysis to any MCP-compatible AI application.

The leading implementation, Crystal DBA’s Postgres MCP Pro, groups its tools into four areas:

Schema intelligence: list schemas, list objects (tables, views, sequences, extensions), and return an object’s columns, constraints, and indexes. This is how the model learns the database before writing a query.
Query execution: run SQL against the database, honoring read-only limits when restricted mode is set.
Query plans: return the EXPLAIN plan for a statement and simulate the impact of hypothetical indexes before they are created.
Database health: analyze index health, connection utilization, buffer cache, vacuum health, sequence limits, and replication lag, the same checks an experienced DBA runs.

The server exposes tools only; it registers no MCP resources and no MCP prompts. Every interaction is a tool call costing 500 to 2,000 tokens of context window, which rewards targeted queries over wholesale schema dumps. A plain connection-wrapper server exposes only the query and execute tools, without the health and index-tuning depth. That difference is the reason to choose one implementation over another.

Which Postgres MCP Server Should You Install?

Install Crystal DBA’s Postgres MCP Pro for the richest feature set, or a managed gateway like Neon or Supabase for cloud databases. Do not install the archived Anthropic reference server.

The reference server is the trap. Anthropic deprecated @modelcontextprotocol/server-postgres on July 10, 2025 and archived it on GitHub, npm, and Docker Hub, after security researchers found a SQL injection in it. The deprecated npm package still draws 21,000 downloads per week, carried by tutorials written before the archive (Datadog Security Labs, August 2025). It connects to current clients without error. That silent success is why the download number stays high, and why installing it is a mistake.

Four current options replace it:

Postgres MCP Pro (Crystal DBA): the feature leader, with index tuning, EXPLAIN-plan simulation, database health checks, and configurable read/write access. It carries over 2,400 GitHub stars and an MIT license. One caveat belongs in any honest evaluation: the project’s most recent commit is from January 2026, with open issues dating back further (pgEdge, April 2026). It is the most capable implementation. Its maintenance pace is the kind of signal the evaluation rubric exists to catch.
Zed Industries fork: the security patch. It eliminates the SQL injection the reference server shipped and is published as @zeddotdev/postgres-context-server. Use it when leaving the reference server is the only change you want to make.
pgEdge Postgres MCP Server: an actively maintained alternative with a custom-tool system that exposes PL/pgSQL as MCP tools, built for ongoing production use.
Managed gateways: Neon, Supabase, Google Cloud SQL Toolbox, and Amazon Aurora expose managed Postgres through platform-native IAM. The cloud platform handles authentication, so no raw connection string is involved.

For Supabase specifically, the dedicated guide covers its project-scoped server: Supabase MCP server.

What Is the Postgres MCP Connection String?

The connection string is a single URI that tells the server which database to reach: postgresql://username:password@host:port/database. Every connection-wrapper server takes it, usually through a DATABASE_URI environment variable.

The URI has five parts, and each one matters:

username:password: the database role the model connects as. This is where read-only enforcement begins, covered in the safe-SQL section below.
host: localhost for a database on your machine, a hostname or IP for a remote one, or a cloud provider’s endpoint.
port: 5432 is PostgreSQL’s default. The 5432 versus 5433 question comes up when a second Postgres instance or a connection pooler occupies the default and pushes the database to 5433. Check the port the database listens on.
database: the specific database name on that server.

One Docker behavior trips up local connections. When the server runs in a Docker container and the database runs on the host, localhost inside the container does not point at the host. The Crystal DBA image remaps it automatically: host.docker.internal on macOS and Windows, and the appropriate host address on Linux. That remap is why a localhost connection string works from inside the container.

Remote connections follow the same URI with the host swapped for the remote endpoint. They require the database to accept connections from the server’s address, over a transport secured with TLS.

How Do You Set Up the Postgres MCP Server?

Set it up in three steps: pull the server through Docker, pipx, or uv; add it to your client’s config with the connection string; then restart the client and verify. Crystal DBA’s Postgres MCP Pro supports all three install methods.

The three install methods:

# Docker
docker pull crystaldba/postgres-mcp

# pipx
pipx install postgres-mcp

# uv (install, then run with the connection string)
uv pip install postgres-mcp
uv run postgres-mcp "postgresql://readonly_user:password@localhost:5432/mydb"

The Docker config for Claude Desktop, with the connection string in an environment variable and read-only access set:

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

The --access-mode=restricted flag sets read-only behavior; unrestricted allows writes. The env block keeps the password out of the command itself. A pipx or uv install swaps the command from docker to postgres-mcp, passing the connection string as an argument rather than through DATABASE_URI. After saving, fully quit and reopen the client, then confirm the server’s tools appear and one schema-list call returns real tables.

How Do You Set It Up in Each Client?

The connection string and command stay the same across clients; only the config file location and restart behavior change.

Claude Desktop: the Docker config above in claude_desktop_config.json, then a full quit and relaunch. The walkthrough: set up MCP in Claude Desktop.
Cursor: the same server entry in .cursor/mcp.json at the project root, which keeps the database connection scoped to that project.
Claude Code: register from the terminal with claude mcp add, passing the Docker command and DATABASE_URI. Claude Code picks up the database context automatically and is well suited to migrations and performance analysis.
VS Code: the same entry in .vscode/mcp.json under the servers root key, not mcpServers.
Windows: the config sits under %APPDATA%\Claude\, and pipx or uv installs need the runtime on the same OS as the client; the Docker path avoids that entirely.

Can Claude Connect to a Postgres Database?

Yes. Claude connects to PostgreSQL through a Postgres MCP server configured with the database connection string, then reads the schema and runs SQL in natural language. The connection works in Claude Desktop, Claude Code, and Cursor, and the same setup answers the adjacent questions this cluster asks.

Can Claude query a database: yes, through the server’s query tool, which runs SQL the model writes and returns the rows. Can Claude access your database: yes, through the role in the connection string, and only with the privileges that role holds. Claude cannot exceed the connection’s permissions, which is why the role is the control point. A read-only role means the model reads and reasons over the data but cannot modify it, regardless of what the conversation asks for.

This is the path behind queries like “connect claude to postgres” and “claude database access”: one server, one connection string, one deliberately scoped role.

The server is connected and the role is set. What remains is what to run on it, where the edges sit, and how to keep a live database safe.

What Can You Build with the Postgres MCP Server?

The dominant workflows are natural-language querying, schema exploration, index tuning, and performance analysis.

Natural-language queries: ask a question in English, and the model writes the SQL, runs it, and returns the answer. “Revenue by region last quarter” becomes a GROUP BY query without anyone writing it by hand.
Schema exploration: point the model at an unfamiliar database and ask how it is structured. It lists schemas, reads table definitions, and explains relationships, useful before joining a new project.
Index tuning: Postgres MCP Pro’s index tuner simulates thousands of candidate indexes against the workload, then recommends the ones that help. The recommendation is cost-based, not guesswork.
Performance analysis: the model reads EXPLAIN plans, identifies slow queries from pg_stat_statements, Postgres’s query-statistics view, and proposes fixes. A Claude Code session can analyze a bottleneck and draft the migration to resolve it.

Each chained workflow spends 5,000 to 8,000 tokens across its calls on top of the server’s registered tool definitions, the same budget logic every connected server follows.

Is the Postgres MCP Server Safe?

The server is safe when the model connects through a dedicated read-only role. Read-only at the database level is the boundary that holds, because a server’s own read-only setting can be bypassed.

The mechanism matters, because read-only is the boundary most database setups get wrong. The archived reference server wrapped queries in read-only transactions but accepted statements separated by semicolons. That gap is exploitable. COMMIT; DROP SCHEMA public CASCADE; works because the COMMIT ends the read-only transaction, and everything after the semicolon runs with the connection’s full privileges (boringSQL, April 2026; Datadog Security Labs, August 2025). A read-only transaction is not a security boundary when the protocol accepts semicolons.

Four controls close the gap:

Connect through a dedicated read-only role. Create a PostgreSQL user with CONNECT, USAGE, and SELECT on the schemas the model needs, and nothing more. A role that cannot write blocks any injected statement from writing, whatever the server’s own guardrail does.
Never connect as a superuser. A postgres superuser connection gives an injected DROP or ALTER full effect. The role in the connection string is the real control.
Set read-only mode where the server offers it. Postgres MCP Pro’s --access-mode=restricted adds a second layer on top of the role, with safe SQL parsing. Use both; rely on the role.
Keep credentials in environment variables. The connection string carries a password. Inject it through DATABASE_URI, never hardcoded in a config file in plain text.

How Does It Compare to Supabase and Cloud Gateways?

Pick the Postgres server for a database you host and connect to directly. Pick a managed gateway when the database lives on a cloud platform that handles auth for you.

Postgres MCP Pro is the choice for a self-hosted or directly-reachable PostgreSQL database, where you control the connection string and the role. It carries the deepest tooling: index tuning, health checks, plan simulation.
Supabase wraps a Postgres database plus auth, storage, and edge functions, and its server is vendor-maintained. A team already on Supabase takes that server: Supabase MCP server.
Neon and cloud gateways expose managed Postgres through platform-native IAM, so authentication runs through the platform instead of a raw connection string. This suits cloud-first setups and teams that prefer not to manage credentials in config.

The decision is infrastructure, not features: where the database lives chooses the server.

Postgres MCP Server Questions

Is the Postgres MCP Server Free?

Yes. Postgres MCP Pro is free and open-source under the MIT license, and the Zed and pgEdge implementations are open-source as well. The only costs are the context-window tokens the tool calls consume and any hosting bill for the database itself.

Is the Postgres MCP Server Read-Only?

It can be, and for analytics it should be, but read-only is not on by default. Set --access-mode=restricted on Postgres MCP Pro, then connect through a database role with only SELECT privileges. The role is the boundary that holds; the server flag is a second layer on top of it.

Does Anthropic Maintain the Postgres MCP Server?

No. Anthropic deprecated its reference Postgres server in July 2025 and archived it after a SQL injection was found. Current setups run Crystal DBA’s Postgres MCP Pro, the Zed Industries fork, or pgEdge. The deprecated npm package still draws downloads; do not install it.

What Port Does the Postgres MCP Server Use?

The server connects to PostgreSQL’s port in the connection string, which is 5432 by default. A database moved to 5433, which happens when a pooler or a second instance holds 5432, needs that port in the URI. The MCP server itself adds no new port for stdio setups; SSE-transport setups expose one, commonly 8000.

Every capability on this page runs through one decision: the role in the connection string. Scope it read-only, point it at the right database, and the rest is one restart away.

What Does the Postgres MCP Server Do and How Do You Set It Up?