MCP PostgreSQL Server

@antonorlov

Repository Homepage Documentation

Basic information

About MCP PostgreSQL Server

MCP PostgreSQL Server

#postgres #postgresql #database #sql #mcp-server #ssh-tunnel

MCP PostgreSQL Server config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-postgres-server"
      ],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb",
        "PG_ALLOW_WRITE": "false"
      }
    }
  }
}

MCP PostgreSQL Server tools

Run one read-only SQL statement against the connected PostgreSQL database and get rows back as JSON. Send exactly one statement per call (SELECT, WITH, EXPLAIN, or SHOW). It runs inside an engine-enforced read-only transaction, so any write is refused by the database. Use this tool for all data reading, aggregation, and query planning. Returns {rows, rowCount, returnedRows, truncated}, plus hint when truncated is true. Prefer $1, $2 placeholders with the params array over interpolating values. Results are capped at ~32768 bytes; truncated:true means rows were dropped - add LIMIT/WHERE or select fewer columns.

Run a data-modifying SQL statement (INSERT/UPDATE/DELETE or DDL). Currently DISABLED: the server is read-only, so this returns an error and changes nothing. To enable writes, the operator must start the server with PG_ALLOW_WRITE=true.

List every schema in the connected database. Start here when exploring an unfamiliar database, then call list_tables for the schema you care about. Returns {schemas: [name, ...]}.

List all tables in a schema (default: 'public'). Use this before querying tables you have not seen yet, then call describe_table for column details. Returns {tables: [name, ...]}.

Show the structure of one table: column names, data types, nullability, defaults, and primary-key membership. Call this before writing non-trivial queries against a table. Returns {columns: [{column, type, nullable, default, is_primary_key}, ...]}.

Overview

What is MCP PostgreSQL Server?

An MCP server that connects an AI agent to a PostgreSQL database over stdio. It reaches local and Docker databases, managed Postgres on RDS, Neon and Supabase, and a database that is only available through an SSH bastion. Writes are off by default.

How to use MCP PostgreSQL Server?

Run it with npx -y mcp-postgres-server and point it at a database with a single DATABASE_URL. It works in any MCP client that speaks stdio: VS Code, Cursor, Claude Code, Codex, Windsurf. Set PG_ALLOW_WRITE=true when the agent should be able to write.

Key features of MCP PostgreSQL Server

Read-only by default, enforced by PostgreSQL itself with a rolled back BEGIN READ ONLY transaction, not by client-side SQL parsing
SSH tunneling to a bastion, using the local port forwarding that PostgreSQL's own documentation describes, with mandatory host-key pinning
DATABASE_URL with full TLS control: sslmode from disable to verify-full, custom CA
Prepared-statement parameters $1, $2, bound by the driver, never spliced into SQL text
Result byte budget with an explicit truncated flag
Errors returned as readable tool results with a code and a hint
Four runtime dependencies, MIT

Use cases of MCP PostgreSQL Server

Letting an agent read a real schema instead of guessing it
Ad-hoc analysis over a replica or a snapshot
Reaching a database that is not routable from the laptop, through an SSH jump host
Inspecting rows and constraints while debugging a failing test

Frequently asked questions

Can it write to my database?

Only when you set `PG_ALLOW_WRITE=true`. With the default off, the `execute` tool is visible but refuses, and every read runs inside a read-only transaction that PostgreSQL rolls back.

What parameter placeholder styles are supported?

PostgreSQL-style `$1`, `$2` only. The legacy `?` style was removed in 0.2.0.

Does it work through an SSH bastion?

Yes. Set `PG_SSH_HOST` plus auth and a pinned `PG_SSH_FINGERPRINT`. Host-key verification is mandatory and the tunnel refuses to connect without it.

Comments

More Databases MCP servers

Neon MCP Server

neondatabase-labs

MCP server for interacting with Neon Management API and databases

617

Lawstronaut

Lawstronaut-FZCO

Access millions of official legal and regulatory source documents from 155+ jurisdictions via MCP. Lawstronaut supports AI agents with structured legal research, legal data, laws, regulations, cases, guidance, official s