PostgreSQL 只读 MCP Server

该本地 MCP Server 使 Codex、Claude Desktop、Cursor 等 MCP 客户端能够安全地查询一个或多个 PostgreSQL 数据库。

安全模型

• query_readonly 仅接受一条 SELECT、VALUES、SHOW 或 EXPLAIN 语句，并始终在 BEGIN READ ONLY 事务中执行。

• 表结构相关工具同样运行在只读事务中。

• 所有工具都设置了语句超时，并且最多返回 MCP_MAX_RESULT_ROWS 行。

• 可通过 DATABASE_URLS 配置多个命名数据库。每次工具调用选择一个目标库，不支持把不同 PostgreSQL 实例直接作为同一 SQL 的跨库 JOIN。

• create_function 可直接创建任意 Schema 下的新函数；仅允许 CREATE FUNCTION，拒绝 CREATE OR REPLACE，同名时由 PostgreSQL 报错且不会覆盖。

• create_pkg_bill_function 保留为兼容别名，行为与 create_function 相同。

• 除函数创建外，其他任何可能修改数据库的语句，必须经你在本机明确审批后才允许执行。

• execute_approved_write 每次执行后都会消费审批记录，防止重复执行。

• 数据库角色权限是最终安全边界。日常查询应使用专用只读角色；确需执行已审批写操作时，应使用独立的受限写角色，并仅在需要时以该角色启动单独的 Server 实例。

MCP 协议无法保证客户端一定向人工展示交互式审批弹窗。因此审批边界刻意放在 MCP 工具之外：只有在本机终端执行命令，才能批准待执行的写操作。

Related MCP server: Postgres MCP Server

安装与运行

npm install
cp .env .env
# 在 .env 中填写 DATABASE_URL 或 DATABASE_URLS 后执行：
npm start

Server 使用 stdio 通信。接入 MCP 客户端时不要手动启动；应由客户端负责创建和管理该进程。

配置 Codex

将以下内容加入 ~/.codex/config.toml，并替换项目路径和连接字符串：

[mcp_servers.postgres_safe]
command = "node"
args = ["/Users/solot/Documents/workplace/python/mcp/src/server.js"]

[mcp_servers.postgres_safe.env]
# 单库旧配置仍然支持，并自动作为名为 default 的数据库：
DATABASE_URL = "postgresql://ai_reader:replace_me@127.0.0.1:5432/taxon"
# 多库时可使用 JSON 对象，键名就是工具参数 database 的值：
# DATABASE_URLS = '{"orders":"postgresql://ai_reader:replace_me@127.0.0.1:5432/orders","users":"postgresql://ai_reader:replace_me@127.0.0.1:5432/users"}'
MCP_STATEMENT_TIMEOUT_MS = "10000"
MCP_MAX_RESULT_ROWS = "100"
MCP_APPROVAL_DIR = "/Users/solot/.local/share/postgres-safe-mcp/approvals"

保存配置后重启 Codex。

配置 Cherry Studio

在 Cherry Studio 的 MCP 服务配置中导入或新增该 Server，命令、参数和环境变量与上面的 Codex 配置保持一致。

只读工具

• list_schemas

• list_tables

• describe_table

• query_readonly

• explain_query

自由 SQL 查询中建议主动加入 LIMIT，Server 也会对返回结果行数进行限制。

所有数据库工具均支持可选的 database 参数，未提供时使用 default。多库数据需要分别查询后由客户端关联；若确实需要 SQL 层跨库 JOIN，应在 PostgreSQL 侧使用 FDW 并严格授予只读权限。

直接创建函数

使用 create_function 传入单条 CREATE FUNCTION [schema.]<函数名>(...) SQL，可直接执行，无需生成审批文件。

• 不允许 CREATE OR REPLACE FUNCTION。

• 不允许包含第二条 SQL，例如单独的 COMMENT ON FUNCTION。

• 函数同名或签名相同时，PostgreSQL 会返回错误，原函数保持不变。

显式审批写操作

1. 让 MCP 客户端调用 request_write_approval，提交一条 INSERT、UPDATE、DELETE、非函数创建 DDL 或其他修改类 SQL。

2. 在本机查看生成的待审批 JSON 文件，其中包含完整 SQL 与 SHA-256 摘要。

3. 在终端中批准该请求：

   npm run approve-write -- <request_id>

4. 之后客户端才能使用该请求 ID 调用 execute_approved_write。每个审批请求仅能执行一次。

执行该进程的数据库角色必须具备对应的写权限。若仍使用只读 PostgreSQL 账号，已审批写操作会因权限不足而失败，这是预期行为。

推荐的 PostgreSQL 角色

为日常查询创建仅具备读取权限的角色：

CREATE ROLE ai_reader LOGIN PASSWORD 'replace_me';
GRANT CONNECT ON DATABASE taxon TO ai_reader;
GRANT USAGE ON SCHEMA public TO ai_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ai_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO ai_reader;

日常 Codex MCP 配置中不要复用数据库超级用户。

验证 Server

npm test
npx @modelcontextprotocol/inspector node src/server.js

数据库调用需要设置 DATABASE_URL 或 DATABASE_URLS。审批请求会绑定创建时选择的数据库，执行时必须使用同一个 database。单元测试不依赖数据库。