Kaiva Postgres MCP

Kaiva Postgres MCP

始终保持只读的 Postgres MCP 服务。可直接替换已归档的 @modelcontextprotocol/server-postgres。

一行切换

如果 AI 客户端目前通过以下方式启动已归档的服务：

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

请更改软件包名称：

      "args": ["-y", "@kaiva/postgres-mcp", "postgresql://localhost/mydb"]

在 Claude Code 中：

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

query 工具、它的 sql 输入以及表结构资源都相同，因此其他内容无需更改。

设置好环境变量 DATABASE_URL 后，还可通过以下方式使用：

• Claude Code 插件：/plugin install postgres-mcp --marketplace ai-kaiva/postgres-mcp
• Gemini CLI 扩展：gemini extensions install https://github.com/ai-kaiva/postgres-mcp，然后运行 gemini extensions config kaiva-postgres-mcp 输入数据库 URL
• Docker：镜像发布后，运行 docker run -i --rm -e DATABASE_URL ghcr.io/ai-kaiva/postgres-mcp

为什么要切换

已归档的服务不再维护：Anthropic 于 2025 年将其归档，作为参考示例而非生产软件，npm 也将其标记为“不再支持的软件包”。它会在 BEGIN TRANSACTION READ ONLY 内执行收到的任意文本，但这并不足够安全：

• COMMIT; DROP SCHEMA public CASCADE 会结束只读事务并删除架构（Datadog Security Labs 于 2025 年 8 月报告了此问题；修复从未进入 npm，0.6.2 仍是最新版本）。
• 使用超级用户登录（大多数本地和 Docker 安装的默认登录方式）时，一条语句就能在数据库服务器上运行 shell 命令：PostgreSQL 会在只读事务中执行 COPY ... TO PROGRAM。

我们在 PostgreSQL 14 上对照版本 0.6.2 检查了这两种情况：两者都能执行。Kaiva Postgres MCP 会拒绝这两种操作。

	已归档的 0.6.2	Kaiva Postgres MCP
COMMIT 后的第二条语句	执行	拒绝：每次调用只允许一条语句，PostgreSQL 本身也会拒绝第二条
COPY ... TO PROGRAM、读取服务器文件、dblink	如果登录账号允许，则执行	拒绝
时间限制	无	每条语句 15 秒，等待锁的时间为 3 秒
返回的行	全部	前 1,000 行，并会说明这一点
超级用户登录	按原样使用	在本机上会发出警告；对于其他机器上的数据库会拒绝，除非你允许
列出的表	仅 public 架构	所有架构
日期和时间戳	转换为 JavaScript 日期，可能导致日期偏移到前一天	与 PostgreSQL 打印的内容完全一致
错误	作为协议错误返回	返回给 AI，并说明如何修复
维护状态	否	是

工具

• query：运行一条只读 SQL 语句（SELECT、WITH、VALUES、TABLE、SHOW 或 EXPLAIN），并以 JSON 格式获取行。
• list_tables：此登录账号可读取的表和视图，包含类型、估算行数和注释。
• describe_table：某个表的列、主键、唯一键和外键、引用该表的表以及它的索引。

资源：每个表的列，与已归档服务列出的内容相同。

如何强制只读

每次调用时：

1. SQL 在发送前会经过检查：只能有一条语句，且必须以 SELECT、WITH、VALUES、 TABLE、SHOW 或 EXPLAIN 开头；不得调用超出事务范围的函数（dblink、服务器文件函数、 lo_import 和 lo_export、pg_terminate_backend、咨询锁，以及以文本形式接收 SQL 并运行它的函数）。
2. 语句会通过 PostgreSQL 扩展查询协议单独运行，该协议会拒绝第二条语句；执行时处于 READ ONLY 事务中，并设有语句时间限制和锁等待时间限制。
3. 事务始终会回滚，并通过 DISCARD ALL 重置会话，因此语句设置的任何内容都不会在事务结束后继续存在。

从数据库中最多只会提取前 1,000 行（还会多读取一行，以确认是否存在更多结果），因此查询大型表时也能快速返回。

使用只能读取的登录账号

最可靠的防护措施是使用无法写入的登录账号。以管理员身份运行一次，然后在连接 URL 中填写 mcp_readonly：

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;  -- PostgreSQL 14 and later
ALTER ROLE mcp_readonly SET default_transaction_read_only = on;

查看登录账号可以执行哪些操作：

npx -y @kaiva/postgres-mcp postgresql://mcp_readonly:...@localhost/mydb --check

选项

选项	默认值
--max-rows <n>	1000	每次查询返回的行数，范围为 1 到 10000
--timeout <seconds>	15	每条语句的时间限制，范围为 1 到 300
--allow-superuser	关闭	允许在另一台机器上的数据库使用超级用户登录。在 Docker Compose 中，数据库位于另一个容器中，因此此选项也适用于这种情况；更好的做法是使用只读登录账号
--check		连接一次，报告登录账号可以执行哪些操作，然后退出

将连接 URL 作为第一个参数提供，或设置 DATABASE_URL。TLS 设置放在 URL 中 （sslmode、sslrootcert），与 psql 中的用法相同。

它无法防护的内容

• AI 可以读取登录账号能读取的所有内容：表、视图和外部表；如果使用超级用户登录，还包括系统目录（pg_authid 中存有密码哈希）。请使用只能查看你打算共享的表的登录账号。
• 拒绝函数列表是第二道防护，不是沙箱。它会检查 AI 发送的 SQL，而不会检查视图、外部表（file_fdw）或数据库中已定义的函数在读取时会执行什么操作。使用超级用户登录时，这类对象仍然可以读取数据库服务器上的文件。使用只能读取的登录账号时，PostgreSQL 本身会拒绝操作（已验证：基于 pg_read_file 的视图会以超级用户身份读取文件，因此只读登录账号会遭到拒绝）。
• “本机”指 localhost、127.x、::1、Unix 套接字、*.localhost 和 host.docker.internal（Docker 主机）。除此之外的任何位置，包括 Docker Compose 服务名称和私有网络地址，都会拒绝超级用户登录，除非提供 --allow-superuser。

在 Claude.ai、ChatGPT 中使用或供团队使用

此软件包在你的机器上运行。若要从 Claude.ai 或 ChatGPT 使用同一个数据库，或在登录验证后与团队共享，Kaiva Bridge 可将其作为托管 MCP 服务提供。在 .env 存有 DATABASE_URL 的项目文件夹中：

npx @kaiva/bridge push mydb --db

你的数据库必须可从互联网访问。https://kaiv.ai/bridge?utm_source=postgres-mcp&utm_medium=readme

许可证

MIT