Postgres MCP Server

The Postgres MCP server is an official reference implementation from the Model Context Protocol team that gives AI agents read-only access to a PostgreSQL database. It exposes a single query tool for running SELECT statements and automatically surfaces table schemas as MCP resources, so an agent can understand your data model before touching it. All queries run inside a READ ONLY transaction, which makes it safe to hand to any agent without worrying about accidental writes.

If you have ever watched an AI agent confidently hallucinate your database schema, you understand why giving it real access matters. The Postgres MCP server solves that problem at the root: it connects your MCP client directly to a PostgreSQL database, exposes every table schema as a readable resource, and lets the agent run SELECT queries whenever it needs actual data. No wrapper, no approximation, no guesswork.

What the Postgres MCP server does

The server is a thin bridge between your MCP client and a PostgreSQL database. It exposes two things:

One tool: query. It accepts a SQL string, runs it inside a READ ONLY transaction, and returns the result set. The agent cannot execute anything that modifies data. If it tries, the transaction wrapper will reject it at the driver level before the statement even reaches the database engine.

One set of resources: Every table in the connected database is automatically discovered and exposed as a resource at postgres://<host>/<table>/schema. Each resource contains the column names and data types for that table in JSON schema format. An agent can read these resources before writing any SQL, which means it starts with accurate knowledge of your actual schema instead of guessing from training data.

That is the entire surface area of the reference implementation. It is deliberately narrow, and that narrowness is a design choice, not an oversight.

Why read-only is the right default

The read/write debate around database MCP servers comes up constantly. Some teams want their agent to INSERT rows, update records, or run migrations. The reference implementation says no to all of that, and it is correct to do so.

Here is the practical reason: an AI agent making autonomous database writes without a human checkpoint is a risk profile that most teams should not accept until they have established trust with the specific agent and task. A misunderstood instruction, an ambiguous prompt, or a hallucinated WHERE clause can cause data loss that is expensive to recover from. Read-only removes that category of failure entirely.

For any agent that needs to understand your data (to answer a business question, generate a report, debug an API response, or help you write a query), read-only access is all it needs. The reference Postgres MCP server covers that use case cleanly.

If you genuinely need write access, the right move is a community fork with write tools added, combined with a dedicated database user that has only the specific permissions required. Never connect a write-enabled MCP server to a superuser or admin credential.

Setup

The install path is straightforward. You need Node.js 18 or later and a valid PostgreSQL connection string.

Test it first with npx:

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

This runs the server inline without a global install. If it connects and prints the schema discovery output, your connection string is correct.

Add it to Claude Desktop:

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

Or run it with Docker:

docker run -i --rm mcp/postgres postgresql://host.docker.internal:5432/mydb

On macOS, use host.docker.internal instead of localhost when the database runs on the host machine. The container cannot resolve localhost to your host network.

For Claude Code, the config file lives at ~/.claude/mcp.json by default. The structure is identical to the Claude Desktop format above.

Common use cases

Schema-aware code generation: An agent working on your backend can read the actual table schemas before generating SQL queries or ORM models. This eliminates the category of bugs that come from stale documentation or out-of-date type definitions.

Data debugging: When an API endpoint returns unexpected results, an agent equipped with the Postgres MCP server can run the actual query against the actual database and compare the result with what the application layer produces. No more "can you check what's in the database" back-and-forth.

Business intelligence queries: Non-technical teammates can describe what they want in plain language and let the agent translate that into SQL, run it, and return the result. The agent has real schema context so the generated queries are more likely to be correct.

Automated reporting: Agents like Cline can be configured with the Postgres MCP server to pull data on a schedule, format it, and drop it into a report or dashboard. The read-only constraint fits this pattern well: the agent reads but never modifies.

Database documentation: An agent can systematically walk through every table resource, inspect schemas, sample data, and generate accurate documentation for a database that has grown organically without documentation. This is tedious for humans and routine for agents.

Security considerations

The reference implementation handles the most important risk by default: no writes. But there are a few other things to think through before pointing it at any database that holds sensitive data.

Use a restricted database user. Create a dedicated PostgreSQL user with SELECT-only privileges on the specific schemas and tables the agent needs. Even though the server enforces READ ONLY transactions, a restricted user provides defense in depth at the database level.

CREATE USER mcp_agent WITH PASSWORD 'strongpassword';
GRANT CONNECT ON DATABASE mydb TO mcp_agent;
GRANT USAGE ON SCHEMA public TO mcp_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_agent;

Avoid embedding credentials in config files checked into version control. Pass the connection string via an environment variable and reference it in your config:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "${POSTGRES_URL}"
      }
    }
  }
}

Use a read replica for production. Connecting an agent to your primary write server adds latency and resource contention. A read replica isolates agent query load from your application traffic and gives you an additional safety layer.

Audit what the agent queries. PostgreSQL's log_statement = 'all' setting on the replica lets you see every query the agent runs. After a few sessions you will have a clear picture of whether the agent is querying sensibly.

Alternatives and the community ecosystem

Because the reference implementation is archived, several community projects have picked up the pattern and extended it:

• mcp-server-postgres (community forks): Several teams maintain active forks with write capabilities added. Search the MCP server directory for current options.
• Supabase MCP server: If your project already runs on Supabase, their official MCP server is better integrated and covers more than raw SQL queries.
• PlanetScale / Neon MCP servers: Cloud-native Postgres providers have started shipping their own MCP servers with platform-specific features like branch management and serverless connection pooling.

For most local development and internal tooling use cases, the reference implementation is still the right starting point. It is stable, well-understood, and the npx path means no installation overhead.

If you are evaluating AI coding agents to pair with this server, Claude Code and Cline both have strong MCP support and are worth comparing. The best AI agent for coding roundup covers the current options in more depth.

Bottom line

The Postgres MCP server does one thing well: it gives an AI agent accurate, live access to your database schema and the ability to run read-only queries. The read-only constraint is not a limitation. It is the only responsible default for a tool that removes a human from the query execution loop.

For any agent workflow that involves understanding data, debugging queries, or generating SQL, this server belongs in the config. Set it up against a restricted user on a read replica, and you get real database awareness with a risk profile that is easy to defend.

Features

• Execute SELECT queries through the query tool
• Automatic schema discovery for every table in the database
• Table schemas exposed as MCP resources (postgres://host/table/schema)
• READ ONLY transaction enforcement at the database driver level
• Zero-config install via npx or Docker
• Plain PostgreSQL connection string auth
• MIT licensed reference implementation

How to set up the Postgres MCP Server MCP server

1. Copy your PostgreSQL connection string in URI format (postgresql://user:pass@host:5432/dbname)
2. Run npx -y @modelcontextprotocol/server-postgres postgresql://your-connection-string to test
3. Add the server block to your Claude Desktop or Claude Code MCP config file
4. Restart your MCP client and verify the query tool and schema resources appear