antonorlov/mcp-postgres-server

A Model Context Protocol (MCP) server for PostgreSQL: local, Docker, RDS, Neon,
and Supabase databases.
The server is small and auditable, with four runtime dependencies: the MCP SDK,
pg, pg-connection-string, and zod (plus ssh2, an optional dependency used
only for SSH tunneling).
Requires Node.js 20 or newer.
Quick start
The preferred way to configure the server is a single DATABASE_URL:
With PG_ALLOW_WRITE set to "false" the server has **read-only access** to the
database. This is the default; set it to "true" only if the model must write.
The same JSON works in any MCP client that speaks stdio: VS Code, Cursor, Claude Code, Codex, Windsurf.
Alternatively, set the individual PG_* variables; they are used when
DATABASE_URL is not set:
Manual Installation
Or run directly with:
Connect to your database
**Local Postgres:**
**Postgres in Docker:** if the database runs in a container with a published
port, connect to localhost: as usual. If the *MCP server
itself* runs inside a container and the database runs on your host machine,
use host.docker.internal instead of localhost:
**Amazon RDS:**
**Neon:**
**Supabase:**
Tools
Tool availability depends on configuration:
| Tool | Available |
|------|-----------|
| query, list_schemas, list_tables, describe_table | Always |
| execute | Always (refuses writes unless PG_ALLOW_WRITE=true) |
| connect_db | Only when PG_ENABLE_RUNTIME_CONNECT=true |
1. query
Execute a read-only SQL statement. Accepts SELECT, WITH ... SELECT,
EXPLAIN, and SHOW. One statement per call - multi-statement input is rejected
by the extended query protocol. In read-only mode (the default) the statement runs
as BEGIN READ ONLY, the query, and ROLLBACK - three commands, roughly two
network round trips with pipelining - so the database itself refuses any write.
With PG_ALLOW_WRITE=true the statement is sent directly, without that wrapper, so a
write run through query would execute - use execute for writes.
Supports PostgreSQL-style $1, $2 prepared-statement parameters; values are bound
by the driver and never spliced into the SQL text.
Returns compact JSON: {"rows": [...], "rowCount": n, "returnedRows": n, "truncated": false}.
When the serialized rows exceed PG_MAX_RESULT_BYTES, only the rows that fit are returned
(returnedRows < rowCount), truncated is true, and a hint suggests adding LIMIT/WHERE
or selecting fewer columns.
2. list_schemas
List all schemas in the connected database.
3. list_tables
List tables in the connected database. Accepts an optional schema parameter
(defaults to 'public').
4. describe_table
Get the structure of a specific table (columns, types, nullability, defaults,
primary keys). Accepts an optional schema parameter (defaults to 'public').
5. execute - requires PG_ALLOW_WRITE=true
Execute an INSERT, UPDATE, DELETE, or DDL statement. Always registered, but
in read-only mode (the default) it refuses with an error naming PG_ALLOW_WRITE
and changes nothing - the statement never reaches the database. With
PG_ALLOW_WRITE=true it runs: same $1, $2 parameter handling as query, one
complete statement per call, and the connecting role governs what it may do.
Returns {"rowCount": n, "command": "INSERT"}.
6. connect_db - requires PG_ENABLE_RUNTIME_CONNECT=true
Connect to a different PostgreSQL database at runtime using provided
credentials. Not registered by default - prefer configuring credentials
through the environment so they never pass through model-visible arguments.
Session limits (statement_timeout, idle_in_transaction_session_timeout) are
re-applied after every reconnect; read-only reads enforce read-only in their own
BEGIN READ ONLY transaction.
Configuration reference
| Variable | Default | Description |
|----------|---------|-------------|
| DATABASE_URL | - | Full connection string (preferred). Supports ?sslmode= in the URL. |
| PG_HOST | - | Database host (fallback when DATABASE_URL is not set) |
| PG_PORT | 5432 | Database port |
| PG_USER | - | Database user |
| PG_PASSWORD | - | Database password |