GUIDE

A drop-in replacement for @modelcontextprotocol/server-postgres

Updated

Kaiva Postgres MCP is a free, open-source (MIT) MCP server that gives Claude Code, Cursor or Claude Desktop read-only access to a Postgres database. It runs on your machine. If you use @modelcontextprotocol/server-postgres, which is archived, change the package name to @kaiva/postgres-mcp and nothing else changes.

Step by step

  1. Change the package nameWhere your AI client starts @modelcontextprotocol/server-postgres, put @kaiva/postgres-mcp instead. The query tool, its sql input and the table resources stay the same, so nothing else changes.
  2. Or add it freshIn Claude Code, run the command below. In Cursor, Claude Desktop or VS Code, add a server whose command is npx -y @kaiva/postgres-mcp followed by your connection URL.
  3. Use a login that can only read (recommended)Create a read-only role with the SQL below and put it in the connection URL. It is the strongest guard: PostgreSQL itself refuses any write.
  4. Check what the login can doRun the same command with --check. It connects once, reports whether the login is a superuser and whether it can change data, and exits.

In Claude Code:

Terminal
claude mcp add postgres -- npx -y @kaiva/postgres-mcp postgresql://localhost/mydb
npx -y @kaiva/postgres-mcp postgresql://localhost/mydb --check

If you use the archived server

@modelcontextprotocol/server-postgres is archived, and its read-only mode can be escaped. Kaiva Postgres MCP keeps the same command, the same query tool and the same table resources, so switching is one word in your config.

How it stays read-only

Every call is checked before it is sent: one statement, starting with SELECT, WITH, VALUES, TABLE, SHOW or EXPLAIN, and no function that reaches past the transaction, such as dblink, server file functions or functions that run SQL given to them as text.

The statement then runs alone, through PostgreSQL's extended query protocol (which refuses a second statement), inside a READ ONLY transaction with a 15-second time limit. The transaction is always rolled back and the session reset, so nothing a statement sets up outlives it. At most 1,000 rows come back, and the answer says when there were more.

It adds two tools beside query: list_tables, for every table and view the login can read, and describe_table, for one table's columns, keys and indexes.

Create a login that can only read

Run this once as an administrator, then put mcp_readonly in the connection URL.

SQL (PostgreSQL 14 and later)
CREATE ROLE mcp_readonly LOGIN PASSWORD 'choose-a-password';
GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
GRANT pg_read_all_data TO mcp_readonly;
ALTER ROLE mcp_readonly SET default_transaction_read_only = on;

In Claude.ai, ChatGPT or for your team

Kaiva Postgres MCP runs on your machine, for the AI clients on that machine. To use the same database from Claude.ai or ChatGPT, or to share it with your team behind sign-in, Kaiva Bridge serves it as a managed MCP server: in a project whose .env holds DATABASE_URL, run npx @kaiva/bridge push mydb --db. The database must be reachable from the internet.

Free includes 10 MCP servers, 200,000 tool calls a month and 200 pages of documents, with no card.

Other ways to do it

  • postgres-mcp-hardenedA read-only Postgres MCP server written in Rust that blocks writes by parsing the SQL, in its own words. Fits if you want a native binary.
  • @yawlabs/postgres-mcpRead-only by default, with EXPLAIN plans, an index advisor and health checks. Fits if you also want database tuning tools.
  • Postgres MCP Pro (postgres-mcp on PyPI)A Python server built for PostgreSQL tuning and analysis. Fits a Python setup or a database administrator's work.
  • DBHub (@bytebase/dbhub)One server for PostgreSQL, MySQL, MariaDB, SQL Server, Oracle and SQLite. Fits if you use several kinds of database.

Questions

Is @modelcontextprotocol/server-postgres still safe to use?
It is archived, npm marks it no longer supported, and its read-only mode can be escaped. Replace it with a maintained server.
Is Kaiva Postgres MCP really a drop-in replacement?
Yes. The command takes the connection URL the same way, the query tool and its sql input are the same, and so are the table schema resources. It adds list_tables and describe_table.
Can the AI change my data?
Not through this server: one read-only statement per call, in a transaction that is always rolled back. A view or function already in your database runs with the login's rights, so use a login that can only read.
Does it send my data anywhere?
No. It runs on your machine and connects only to your database.
Is it free?
Yes. It is open source under the MIT licence.