mcp-handbook

Postgres MCP Server

A Postgres MCP server lets AI assistants query your PostgreSQL database directly. Ask questions in plain English, get SQL results back — no writing queries, no switching to a database client, no exporting CSVs.

What it does

You talk to your AI assistant. It writes the SQL, runs it against your database through the MCP server, and returns the results in a readable format. The AI handles the translation from "how many users signed up last week?" to the actual SELECT statement.

Typical use cases:

  • "How many new users signed up each day this month?" — generates and runs the query, returns a daily breakdown
  • "What's our top-performing product by revenue this quarter?" — joins orders and products, aggregates, sorts
  • "Show me the schema for the users table" — returns column names, types, and constraints
  • "Find all orders over $1,000 that haven't shipped" — filters and returns matching rows
  • "What tables reference the customers table?" — explores foreign key relationships

Why this is useful

Most business questions live in a database. Getting answers usually means either knowing SQL, asking someone who does, or waiting for an analyst to build a report. A Postgres MCP server removes that bottleneck — anyone who can describe what they want can get the answer.

For teams that already know SQL, it's still faster. The AI handles the boilerplate: remembering table names, getting join conditions right, writing the aggregation. You describe the intent, review the query, and get the result.

How to set it up

The official Postgres MCP server from the MCP project works with Claude Desktop, Cursor, and other MCP-compatible clients. Add it to your configuration:

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

Replace the connection string with your actual database credentials. For remote databases, use the full connection URL with SSL if required.

Read-only setup (recommended)

Create a read-only database user for the MCP server. This ensures the AI can query data but can't modify or delete anything:

CREATE ROLE mcp_reader WITH LOGIN 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;

What tools are available

The Postgres MCP server typically provides:

  • query — run a SQL query and return results
  • list_tables — show all tables in the database
  • describe_table — return schema details for a specific table
  • list_schemas — show available schemas

The AI uses these tools together — it'll check the schema first, then write a query that matches your actual table structure.

Security considerations

  • Always use a read-only user for the MCP connection unless you specifically need write access
  • Don't expose production databases directly — use a read replica if available
  • Connection strings contain passwords — keep your MCP config file permissions restricted
  • Be aware of data sensitivity — the AI will see query results. Don't connect to databases with PII unless your usage policy allows it.

Related guides