Postgres MCP Server: Connect Claude & AI Agents to PostgreSQL

⏱️ 3 min read 🔌 MCP Server

What it is: The reference Postgres server from the official modelcontextprotocol/servers repo. It exposes read-only SQL execution and schema introspection over MCP, so any compatible agent can list tables, fetch column metadata, and run queries.

Quick answer: A Postgres MCP server is a small process that speaks the Model Context Protocol and gives AI agents like Claude read-only access to a PostgreSQL database — schema introspection plus SQL execution. Setup is one command: npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb, registered in your Claude Code, Claude Desktop, or Cursor config. Every query runs inside a READ ONLY transaction, so the agent can explore but never write.

Why it matters for data work

The single fastest way to make a coding agent useful against your application database. No need to paste schemas in by hand or build a custom tool — the MCP server handles introspection and Claude figures out the right query.

Install: one command

npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb

That's the whole server. What remains is telling your client to launch it — the config differs slightly per tool.

How do you configure it in Claude Code?

Use claude mcp add, or drop a .mcp.json at the project root so the whole team gets the server. Restart Claude Code (or run /mcp) and the postgres tools appear.

# CLI, one line:
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb

# or project-scoped .mcp.json:
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

How do you configure it in Claude Desktop?

Edit claude_desktop_config.json (Settings → Developer → Edit Config; on macOS it lives at ~/Library/Application Support/Claude/) and fully restart the app — Claude Desktop only reads the file at launch.

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

How do you configure it in Cursor?

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally), then enable the server under Settings → MCP. The JSON shape is identical:

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

Is it really read-only?

Yes, at the transaction level: the server wraps every query in BEGIN TRANSACTION READ ONLY, so INSERT, UPDATE, DELETE, and DDL fail no matter what SQL the model writes. Still, defense in depth is cheap — connect with a dedicated Postgres role that has only SELECT granted, and point dev/staging rather than production at the agent while you build trust. The read-only guarantee protects your data, not your CPU: an agent can still write an expensive query, so set a statement_timeout on the role.

CREATE ROLE ai_readonly LOGIN PASSWORD '...';
GRANT USAGE ON SCHEMA public TO ai_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ai_readonly;
ALTER ROLE ai_readonly SET statement_timeout = '10s';

Why can't my agent see my tables?

Nine times out of ten it's the connection string or the schema. Check these in order: (1) the URL points at the right database name — postgresql://localhost/mydb, not the default postgres db; (2) your tables live in a non-public schema, so the role's search_path or the introspection scope misses them — grant USAGE on that schema and qualify names; (3) the connecting role lacks SELECT on the tables; (4) special characters in the password aren't URL-encoded; (5) you edited the config but didn't restart the client — Claude Desktop and Cursor only pick up MCP changes on restart.

Which Postgres MCP server should you use?

The reference server above is the simplest and safest starting point, but it is minimal by design — and the modelcontextprotocol/servers repo has archived it, so it receives no new features. If you need more, Postgres MCP Pro (crystaldba/postgres-mcp) is the actively developed alternative: EXPLAIN-based query analysis, index tuning advice, health checks, and a configurable restricted vs unrestricted mode. Cloud vendors (Supabase, Neon) also ship their own MCP servers with platform-specific tools.

Server	Write access	Best for
Reference (@modelcontextprotocol/server-postgres)	Never (READ ONLY txn)	Safe schema-aware querying, quickest setup
Postgres MCP Pro (crystaldba)	Optional, mode-gated	Performance tuning, index advice, DBA work
Vendor servers (Supabase, Neon)	Varies	Managing that vendor's platform, not just SQL

Example usage

Ask Claude "which customers signed up last week and haven't placed an order?" — it'll inspect your schema via the MCP server, write the join, run it, and summarize the results. All in one turn.

Author & links

Author: Model Context Protocol project (Anthropic-maintained)

Repo: github.com/modelcontextprotocol/servers

License: MIT

Related skills

Same pattern, different database: the MySQL MCP server and the SQLite MCP server (ideal for local files and prototyping). For warehouse work see the BigQuery MCP server. For dbt-aware semantic context, layer on the dbt MCP skill.

← Back to MCP Servers