Query Postgres from Claude with MCP: A Practical Guide

You can query Postgres from Claude by connecting Claude Code to a PostgreSQL MCP server. Claude then lists your tables, reads their columns and runs SELECT queries for you. You ask in plain English and get an answer backed by a real query. Use a read-only database role and check the SQL behind every number.

What it looks like

Say you ask Claude: "How much did customers pay us in August, by currency?"

Without a database connection, Claude has to guess or ask you to paste data. With a PostgreSQL MCP server connected, it works through the problem itself:

1. It calls list_tables and describe_table to find where orders live.
2. It writes a SELECT and shows you the SQL.
3. It runs the query with the query tool and explains the rows that come back.

The rest of this guide shows how to set that up safely, and how to ask questions that get trustworthy answers.

Set up a read-only connection

Don't reuse your application's owner account. Ask your database admin for a role that can only read the tables you want Claude to see. In Postgres that means a role with SELECT and nothing else. The PostgreSQL privileges docs explain each grant.

A reporting view with a few relevant columns is even better. Claude finds its way around faster, and personal data like emails and free-text notes never reaches the chat.

Then create a PostgreSQL instance in the MCPifex portal. Enter the host, port, database, username, password and SSL mode, and click Test connection. That runs list_schemas against your database, so a wrong password shows up right away. The PostgreSQL server page lists every field and tool.

Connect Claude Code

Generate an API key for the instance, then run this once, with your key in place of the placeholder:

#!/bin/sh
# MCPifex — Claude Code CLI snippet.
# Replace <YOUR_MCPX_KEY> with your MCPifex API key (starts "mcpx_"), from
# the portal's API key page, then run this once from any shell that has the
# `claude` CLI on PATH.
claude mcp add mcpifex --transport http https://mcpifex.com/mcp \
  --header "Authorization: Bearer <YOUR_MCPX_KEY>"

Type /mcp inside Claude Code to confirm it's connected. The key only authenticates you to MCPifex. Your database password stays in the instance and never goes to Claude. More options are in the Claude Code guide.

As of September 2026, list_schemas, list_tables, describe_table and query are on by default. execute, which can insert, update and delete, is off. Leave it off for reporting.

Start by asking about the schema

Before asking for any number, let Claude learn what your tables mean:

Look at the reporting schema. List the tables about orders and describe their columns. Which fields could be the order time, payment status, currency and amount? Ask me about anything unclear before calculating.

This step catches the classic traps. There may be several timestamps: created, paid, shipped and refunded mean different things. An amount might be in cents, or before tax. A status called "complete" might mean shipped, not paid.

Correct Claude where it's wrong, and ask it to summarize what it learned in a short data dictionary. That saves you from repeating yourself in every later question.

Ask for a bounded query

Good questions name the period, time zone and filters, and ask to see the SQL first:

Calculate paid order value by currency for August 2026, using UTC payment timestamps. Exclude test orders. Show me the SQL before you run it, and don't return any personal details.

For a table where those fields are verified, the SQL might look like this. The table and columns are made up for illustration, so swap in your own after inspecting your schema:

SELECT currency,
       count(*) AS paid_orders,
       sum(amount_cents) AS paid_amount_cents
FROM reporting.orders
WHERE paid_at >= TIMESTAMPTZ '2026-08-01 00:00:00+00'
  AND paid_at < TIMESTAMPTZ '2026-09-01 00:00:00+00'
  AND status = 'paid'
  AND is_test = false
GROUP BY currency
ORDER BY currency;

Three details matter here. The start of the range is inclusive and the end is exclusive, so nothing is lost at midnight. It groups by currency, so you never add dollars to euros. And it keeps amounts in cents until you decide how to display them.

Note that this is "paid order value", not net revenue. Refunds and fees live elsewhere, so tell Claude how to treat them before it adds another table.

Check the answer before you trust it

A query that runs isn't the same as a question answered correctly. Before you share a number, check four things:

1. Coverage: the answer names the schema, table, period and filters.
2. Units: amounts have a currency and say cents or whole units. Timestamps have a time zone.
3. Empty results: Claude tells apart "no matching rows", null values and a failed call.
4. Reconciliation: a report you already trust, built on the same definitions, gives matching totals.

Empty results deserve a second look. In Postgres, sum over no rows returns null while count returns zero, as the aggregate docs explain. In the query above, a currency with no paid orders simply doesn't appear. Ask Claude to explain a missing row before you read it as zero sales.

If you follow up with "now by week", tell Claude to keep the original filters. If the total changes, compare the two SQL versions instead of accepting a story about customer behavior.

When a query is slow or fails

Read-only queries can still be expensive. Ask for narrow date ranges and aggregated results, and have your admin set a statement_timeout on the reporting role, as the client connection docs describe. A short result table doesn't mean a small scan.

• Authentication error: test the MCPifex key and the database connection separately. They are different credentials.
• Missing table: check the schema name and the role's privileges.
• Timeout: narrow the question, or hand the SQL to the database owner. Turning on writes won't fix a slow report.

Every call is logged per instance in the portal, so you can compare what Claude ran against what it told you. Save the question, the SQL, the time you ran it and the checks you did. Someone else can then rerun your analysis without replaying the chat.

Where MCPifex fits

MCPifex runs the PostgreSQL server for you, so there's nothing to install and no database password in your shell config. You pick which tools are enabled, and the gateway refuses any call to a tool that's off. If a key leaks, revoke it in the portal. New calls stop within about a minute. The API key docs cover the details, and the free plan includes 3 instances.