PostgreSQL MCP Server Setup Guide 2026: Connect Claude to Your Database

Table of Contents

1. What Is the PostgreSQL MCP Server?
2. Official vs Third-Party Postgres MCPs
3. Prerequisites
4. Step-by-Step Installation
5. Read-Only Mode (Recommended Default)
6. What Claude Can Do With Postgres MCP
7. Real-World Workflows
8. Postgres MCP vs Supabase MCP
9. Common Errors and How to Fix Them
10. Security Best Practices
11. Frequently Asked Questions

What Is the PostgreSQL MCP Server?

The PostgreSQL MCP server (often called the Postgres MCP) is a Model Context Protocol server that gives AI clients direct, schema-aware access to any Postgres database. The official version is part of the modelcontextprotocol/servers repository — the same monorepo that hosts the GitHub, Filesystem, and Slack MCPs.

Once installed, Claude can:

• Introspect your schema (tables, columns, indexes, foreign keys, constraints).
• Execute SELECT queries against any database the MCP can reach.
• Explain query plans, suggest indexes, and walk through performance hotspots.
• Generate migration SQL for schema changes (in read-only mode, it generates — it does not execute).

It is the single most useful MCP for any developer who works with relational data daily. We rank it in the top 3 of our Best PostgreSQL MCP Servers in 2026 roundup, and it appears in nearly every starter config emitted by the Skiln Config Generator.

Official vs Third-Party Postgres MCPs

Skiln indexes more than a dozen Postgres-related MCP servers. The notable ones:

• Official server-postgres from Anthropic. This guide covers it. Most feature-complete, best-maintained, read-only by default.
• OpenClaw Postgres. Community fork with extended schema-diff tooling.
• Supabase Postgres MCP. Bundled with the Supabase MCP — covered separately below.
• MCP Postgres (LobeHub). Lightweight wrapper, smaller footprint, fewer features.
• Postgres Wizard. A higher-level helper that adds query templates and migration scaffolding on top of raw Postgres.

Unless you have a specific reason to deviate, start with the official server-postgres. It is the baseline every other MCP gets compared against.

Prerequisites

You will need:

• A running Postgres database — local (Docker, Postgres.app, asdf) or remote (Supabase, Neon, RDS, etc).
• A database user with at least SELECT access on the schemas you want Claude to query. For read-only use, that is enough. For write access, the user needs the corresponding INSERT/UPDATE/DELETE privileges.
• A connection string in standard Postgres URI format.
• An MCP-compatible AI client. See our Best MCP Clients in 2026 for the lineup.
• Node.js 18+ for the npx runner.

Step-by-Step Installation

Building the Connection String

A Postgres connection string follows this shape:

postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE?sslmode=require

A few notes that save hours of debugging:

• URL-encode special characters in your password. A @ becomes %40, a : becomes %3A. Otherwise the parser splits on the wrong character.
• Use sslmode=require for any remote database. Most cloud providers require SSL, and the default sslmode=prefer will fail silently on some configurations.
• Specify the database name explicitly. Many cloud providers default to a database that does not have your tables.

If you are using Supabase, the connection string is under Project Settings → Database → Connection Pooling (use the pooler for the MCP, not the direct connection, to avoid running out of connections). For Neon, copy the pooled connection string from the dashboard. For self-hosted, localhost:5432 with your local creds.

Configuring Your AI Client

Claude Desktop. Add to claude_desktop_config.json:

{   "mcpServers": {     "postgres": {       "command": "npx",       "args": [         "-y",         "@modelcontextprotocol/server-postgres",         "postgresql://user:pass@host:5432/db?sslmode=require"       ]     }   } }

Restart Claude Desktop. The postgres tool appears in the MCP sidebar.

Claude Code. Use the CLI:

claude mcp add postgres -- \   npx -y @modelcontextprotocol/server-postgres \   "postgresql://user:pass@host:5432/db?sslmode=require"

Cursor. Settings → MCP → Add new MCP server. Command: npx. Args: -y @modelcontextprotocol/server-postgres "postgresql://user:pass@host:5432/db?sslmode=require". Save and restart.

For all three clients, ask Claude "list the tables in this database" as a smoke test. You should see the table list within a second or two.

Read-Only Mode (Recommended Default)

The single most important configuration knob: the official Postgres MCP runs read-only by default. SELECT, EXPLAIN, and schema-introspection queries work. INSERT, UPDATE, DELETE, and DDL statements are rejected with a clear error.

This is the right default. Even if you intend to let Claude write to a database eventually, you should run read-only for the first week while you build trust in how it composes queries. The friction of "Claude cannot insert here" is much smaller than the friction of "Claude deleted a column it should not have."

If you do need write access, the safer pattern is:

• Create a dedicated Postgres user with exactly the write privileges you want Claude to have. Not your admin user.
• Use schema-level permissions to wall off tables Claude must not touch (audit logs, billing, user PII).
• Enable a query audit log so you can review what the MCP executed.

For 95% of analytical workflows — "show me last week's signups by source," "what's the slowest query in this database" — read-only is sufficient and dramatically safer.

What Claude Can Do With Postgres MCP

The MCP exposes a small, focused set of tools. The most useful in practice:

• list_tables — enumerate tables in a schema.
• describe_table — columns, types, indexes, constraints.
• query — execute a SELECT and stream results back.
• explain — return the query plan for a given SQL statement.

Claude composes these into multi-step workflows. A request like "find the 10 slowest queries in pg_stat_statements" turns into a list_tables → describe_table → query chain that Claude orchestrates without further prompting.

Real-World Workflows

The patterns we see most often across the Skiln community:

Ad-hoc analytics. "What's our DAU/MAU ratio for the last 30 days, broken down by signup channel?" Claude reads the schema, writes the SQL, executes it, and presents the result as a Markdown table. Faster than opening a BI tool for a one-off question.

Schema exploration on a new project. "Walk me through this database — what are the main entities, how do they relate, where are the indexes?" Claude introspects, builds a mental model, and explains the schema like a senior engineer would.

Slow-query debugging. "Find the slowest queries in pg_stat_statements, then explain why the top one is slow and suggest an index." Claude pulls the stats, runs EXPLAIN, and proposes an index with the exact CREATE INDEX statement you can review and apply.

Migration sketching. "Write the migration to add a last_login_at column to users, indexed, with a default of NULL." Claude produces idiomatic Postgres migration SQL. In read-only mode you copy it into your migration tool of choice (Drizzle, Prisma, Atlas) — the MCP does not execute it.

Data quality audits. "Find rows in orders where total is NULL but status is completed." Claude writes the SELECT, surfaces the problem rows, and proposes a fix. A common cleanup task that takes 30 minutes manually drops to 30 seconds.

Schema diff for code review. Combined with the GitHub MCP, Claude can pull a PR that touches a migration, run the migration mentally against the current schema, and flag any issues before the PR ships.

Postgres MCP vs Supabase MCP

If your database lives on Supabase, you have two options. They are not mutually exclusive — many developers run both.

Postgres MCP speaks raw SQL. It does not know about Supabase concepts like RLS, auth users, or storage buckets. But it is fast, simple, and works against any Postgres-compatible host. Best for analytical workloads where you just want to query data.

Supabase MCP is a higher-level wrapper. It exposes Supabase's auth and RLS as first-class operations, can deploy edge functions, manages branches, and adds project-level tooling. Best for full-stack development where the database is part of a larger Supabase app.

The pattern most Supabase users settle on: the Supabase MCP for app development and the Postgres MCP for read-heavy analytics queries. Postgres MCP gives you a lightweight read path that does not consume Supabase API quota.

Common Errors and How to Fix Them

The five that account for most support requests:

1. "password authentication failed for user X". Your connection string has the wrong credentials or the password contains URL-special characters that were not encoded. URL-encode @, :, /, and # in the password.

2. "no pg_hba.conf entry for host X". Your cloud Postgres host is not allowing connections from your machine's IP. Most managed Postgres services have an "allowed IPs" list — add your IP, or set it to 0.0.0.0/0 (with a strong password) for development.

3. "SSL connection is required". Add ?sslmode=require to the connection string. Cloud providers reject plaintext connections by default.

4. "relation X does not exist" when you can see it in the dashboard. Wrong schema in the search path. Either qualify the table name (schema.table) in the query or set the search_path for the connection user.

5. The MCP shows green but Claude says "I cannot reach the database." The MCP process died after the AI client started. Check the client's MCP logs — usually a connection timeout from a cold database (Supabase free-tier projects sleep after inactivity).

Security Best Practices

• [ ] Connect with a read-only Postgres user — not your admin user.
• [ ] Use per-schema GRANT statements to fence off sensitive tables.
• [ ] Store the connection string in env vars or a secret manager, not the MCP config file in plaintext (where possible).
• [ ] Rotate the database password every 90 days.
• [ ] Enable Postgres query audit logging for production databases.
• [ ] If you must allow writes, use a separate MCP instance with a write-enabled user, and run it only when needed.
• [ ] Add the MCP user's IP to firewall allowlists instead of opening the database to the public internet.

Frequently Asked Questions

Is the PostgreSQL MCP server free?

Yes. The official Postgres MCP from Anthropic's modelcontextprotocol/servers repo is open-source and free. You only pay for the underlying database (your Postgres host) and the AI provider you connect through.

Does the Postgres MCP work with cloud-hosted databases?

Yes. Anything that speaks the Postgres wire protocol works — Supabase, Neon, Render, Railway, AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL, DigitalOcean Managed Databases, and self-hosted Postgres. You just need a connection string the MCP can reach.

Can Claude write to my database via the Postgres MCP?

By default, the official MCP runs in read-only mode and rejects INSERT, UPDATE, DELETE, and DDL statements. You can opt into write mode via configuration, but we strongly recommend keeping the default read-only setting for production databases and using migrations for any schema or data changes.

How does it handle schema discovery?

The Postgres MCP auto-introspects the database when Claude first calls it — it pulls table names, column types, primary keys, and foreign keys via Postgres system catalogs. This means Claude can answer schema questions without you copy-pasting the schema into the chat. Large databases (1000+ tables) take a second or two to introspect.

Does it work with PgVector and other extensions?

Yes. The MCP passes queries through to Postgres without filtering by extension, so PgVector, PostGIS, TimescaleDB, pg_trgm, and any other extension your database has installed are all queryable. Claude will recognize vector and JSON column types and respond accordingly.

Can I connect to multiple databases at once?

Yes. Run multiple instances of the Postgres MCP, each with its own name and connection string. Most AI clients let you register N MCP servers — you can have postgres-prod, postgres-staging, and postgres-analytics all available simultaneously, and Claude will route based on the question.

What's the difference between Postgres MCP and Supabase MCP?

The Postgres MCP speaks raw Postgres — SQL queries, schema introspection, no auth concept. The Supabase MCP wraps Supabase's higher-level concepts: auth users, RLS policies, storage buckets, edge functions, branches. If your database is on Supabase, run the Supabase MCP for full-stack work and the Postgres MCP for read-heavy analytical queries.

Where can I find other database-related MCP servers?

Skiln indexes 50+ database MCPs covering Postgres, MySQL, SQLite, MongoDB, Redis, DynamoDB, BigQuery, Snowflake, and more. Browse them at /mcps with the search term "database" or check our companion ranking of the best PostgreSQL MCP servers for 2026.

Last updated: May 28, 2026 · Skiln tracks Postgres MCP server updates daily across the official repo, Supabase, OpenClaw, and LobeHub.