postgres-mcp
Provides tools for interacting with PostgreSQL databases: read-only queries, table listing, relation descriptions, and connection information by default; readwrite mode adds single write statements and all-or-nothing multi-statement transactions with dry-run support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@postgres-mcp show me the schema of the users table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
postgres-mcp
A small PostgreSQL MCP server for Claude Code and other MCP clients, built to be safe to point at a shared database.
Read-only by default. Write tools exist only when
PG_MCP_MODE=readwrite.One statement per call. Every statement goes through the extended query protocol, which rejects
select 1; drop table t. Transaction control (COMMIT,BEGIN,SET TRANSACTION, ...) is refused.Every call is its own transaction. Reads run in
REPEATABLE READ READ ONLYwith a snapshot taken first, then always roll back; the session also defaults todefault_transaction_read_only=on.Bounded.
statement_timeouton every call; reads go through a cursor and fetch at mostPG_MCP_MAX_ROWS + 1rows; long cells andbyteaare summarised.No password on the command line. Arguments are refused; the connection string comes from the environment, so it does not show up in
psor Task Manager.Pinned. Exact dependency versions, a committed
package-lock.json, andignore-scripts=true.
Written after reviewing @sarmadparvez/postgresql-mcp@1.0.8, whose query tool could be escaped with
COMMIT; <write> because it sent the SQL with the simple query protocol. No code is shared.
Tools
Tool | Mode | What it does |
| always | One read-only statement ( |
| always | Tables, views, materialized views with estimated rows and size; all user schemas by default |
| always | Columns, constraints and indexes of one relation |
| always | Role, mode, limits, and whether the role itself could write |
| readwrite | One write statement, committed; |
| readwrite | Up to 100 statements, all or nothing; supports |
Related MCP server: postgres-mcp-server
Install
git clone https://github.com/cleondev/postgres-mcp.git
cd postgres-mcp
npm ciRequires Node.js 20 or later.
Register with Claude Code
claude mcp add postgres-mydb --scope user \
-e PG_MCP_URL=postgres://reader@db.example.com:5432/mydb \
-- node /path/to/postgres-mcp/src/index.jsKeep the password out of PG_MCP_URL where you can: pg also reads PGPASSWORD and the standard
pgpass file (~/.pgpass, or %APPDATA%\postgresql\pgpass.conf on Windows).
Configuration
Variable | Default | Meaning |
| required |
|
|
|
|
|
| Per-call statement timeout |
|
| Rows returned by |
|
| Characters kept per cell |
Threat model
This server stops a model from writing by accident or by being talked into a multi-statement escape.
It cannot make a role that is allowed to write truly read-only: a function the role may call (for
example dblink_exec, which opens a second connection) runs outside this server's transaction.
connection_info and the startup log warn when that is the case.
For a hard boundary, connect readonly mode as a role that has only SELECT:
create role mydb_reader login password '...';
grant connect on database mydb to mydb_reader;
grant usage on schema app to mydb_reader;
grant select on all tables in schema app to mydb_reader;
alter default privileges for role mydb_owner in schema app grant select on tables to mydb_reader;In readwrite mode, review each execute/transaction call before approving it; do not add those
tools to an auto-approve list.
Tests
npm test # unit tests only
PG_MCP_TEST_URL=postgres://... npm test # plus end-to-end tests over stdioThe end-to-end tests touch only temporary tables, so they are safe against a shared database.
License
MIT
Available Tools
4 toolsconnection_infoConnection and safety infoARead-only
Who this server connects as, its mode and limits, and whether the database role itself could write.
Inputs: no named parameters.
describe_tableDescribe a tableBRead-only
Columns (type, nullability, default, comment), constraints and indexes of one table or view.
Inputs: table (required), schema.
list_tablesList tablesARead-only
List tables, views and materialized views with estimated row counts and size. Omit schema to list every user schema.
Inputs: schema.
queryRun read-only SQLARead-only
Run ONE read-only SQL statement (SELECT, WITH, VALUES, TABLE, SHOW, EXPLAIN) in a READ ONLY transaction that is always rolled back. Returns at most 500 rows; long cells are cut. Multiple statements and transaction control are rejected.
Inputs: sql (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a clearly different need: arbitrary reads (query), object inventory (list_tables), single-object structure (describe_table), and server/session context (connection_info). The only overlap is that query can reach pg_catalog and duplicate the metadata tools, but the descriptions make the intended split clear enough to avoid misselection.
Three of four names follow a recognizable verb/verb_noun style (query, list_tables, describe_table) with snake_case throughout. connection_info is the one break in pattern as a noun phrase, but it still reads naturally as a distinct informational tool.
Four tools is lean and each one earns its place in a deliberately read-only server; nothing feels redundant. It sits at the low end of the comfortable range, so a slightly broader surface (e.g. schema/extension listing) could have been added without bloat.
For a read-only inspection domain, the set covers the main path: discover objects, inspect structure, run ad-hoc queries, and confirm what the role can do. Gaps are minor — no schema/database listing tool, no column-name search, and no dedicated index or function introspection — all workable via query on pg_catalog.
Maintenance
Related MCP Connectors
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Managed Postgres MCP: projects, SQL, docs search, and storage buckets via OAuth.
Read authorized Loam tables and supported external databases through a bounded MCP connection.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Related MCP Servers
- AlicenseAqualityCmaintenanceLocal MCP server for safe querying and inspecting PostgreSQL databases, with write and maintenance operations disabled by default.81MIT
- AlicenseNot gradedqualityDmaintenanceEnables inspecting database schemas and executing read-only SQL queries on a PostgreSQL database via MCP tools.5 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides a read-only PostgreSQL MCP server with schema introspection. Enforces least-privilege database roles to prevent any writes, even from malicious SQL.MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to safely query one or more PostgreSQL databases with read-only tools and explicitly approved write operations.1-