Postgres MCP server setup for Claude Desktop

What the Postgres MCP server does

The Postgres MCP server exposes database tools to Claude Desktop. With it, Claude can list tables, describe schemas, read sample rows, and run SQL queries through a structured interface rather than copying and pasting context into chat.

This is useful for exploring unfamiliar schemas, drafting queries, summarizing data patterns, and pairing on debugging. It is not a replacement for a database IDE, and it should never be given unrestricted write access without review.

Prerequisites

• Claude Desktop installed on macOS, Windows, or Linux.
• Python 3.12 or newer with uv installed (or Docker, if you prefer containers).
• A PostgreSQL database you can connect to, with credentials that support role-based access.
• Basic familiarity with SQL and JSON config files.

Install the server

Do not use the old reference server. The npm package @modelcontextprotocol/server-postgres was archived in 2025 and has an unpatched SQL-injection flaw that lets stacked queries escape its read-only mode. This guide uses Postgres MCP Pro instead, which enforces read-only access by parsing every statement. Run it with uvx so there is nothing to install globally:

uvx postgres-mcp --access-mode=restricted

The --access-mode=restricted flag is essential: the server defaults to unrestricted read/write, and restricted mode rejects any statement that is not a read. Alternatively, use pipx install postgres-mcp or the crystaldba/postgres-mcp Docker image. Verify the command starts without errors in a terminal before adding it to Claude Desktop; it will wait for the connection string, which the config below provides.

Claude Desktop config

Open claude_desktop_config.json. On macOS it lives at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows look in %APPDATA%/Claude. Add the Postgres server under mcpServers:

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

Replace REPLACE_ME with the actual password. The connection string goes in the env block, not in chat. For shared machines, point DATABASE_URI at a secrets-managed file or use the Docker variant with an env file instead of plain JSON.

Database permissions

Create a dedicated read-only role. Do not reuse an application role or superuser account. The principle is simple: the assistant should see only what it needs to see.

CREATE ROLE mcp_readonly WITH LOGIN PASSWORD 'a-strong-random-password';
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

If you want to restrict access further, grant SELECT only on specific tables or create a separate schema with views that expose a sanitized subset of data.

Test the connection

1. Save the config file and restart Claude Desktop completely.
2. Open a new conversation and look for the tools icon or server indicator.
3. Ask Claude: "List the tables in my Postgres database."
4. Then ask: "Describe the schema for the users table."

If Claude returns structured schema information, the connection is working. If it says no tools are available, check the logs.

Troubleshooting

On macOS, you can open the Claude Desktop logs from the Help menu. Look for error messages from the MCP server process; they usually point directly to a missing dependency or bad connection string.