pgmoat

pgmoat

为 AI Agent 提供受管控的 Postgres 访问能力。

pgmoat 是一款开源 MCP 服务，可让 AI Agent 以只读方式访问 Postgres。它使用真实的 Postgres 解析器检查每条查询，隐藏你标记为隐藏的表和列，应用行数限制和超时，根据调用者身份绑定行级安全策略（RLS），并写入防篡改审计日志。

需要 Node.js 22.12 或更高版本，以及 Postgres 15 至 18。

快速开始

使用安全默认值连接到数据库，无需配置文件：

npx -y pgmoat postgresql://readonly_user:password@localhost:5432/mydb

将其添加到 Claude Code：

claude mcp add pgmoat -- npx -y pgmoat postgresql://readonly_user:password@localhost:5432/mydb

或添加到 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "pgmoat": {
      "command": "npx",
      "args": ["-y", "pgmoat", "--url-env", "PGMOAT_DATABASE_URL"],
      "env": { "PGMOAT_DATABASE_URL": "postgresql://readonly_user:password@localhost:5432/mydb" }
    }
  }
}

通过 --url-env 传递 URL，可避免密码出现在进程列表中。

请使用专用只读角色。如果该角色是超级用户或具有写入权限，pgmoat 会在启动时发出警告。

添加说明并隐藏敏感数据

export PGMOAT_DATABASE_URL=postgresql://readonly_user:password@localhost:5432/mydb
npx pgmoat init          # writes pgmoat.yaml; auto-hides columns like password_hash and token_hash
npx pgmoat validate      # checks the file against the schema and the database
npx pgmoat doctor        # checks the role for unsafe privileges
npx pgmoat start         # starts the server with ./pgmoat.yaml

pgmoat.yaml 文件示例如下：

version: 1
server:
  name: mydb
connection:
  url: ${PGMOAT_DATABASE_URL}
  schemas: [public]
mode: read-only
budgets:
  max_rows: 200
  max_query_ms: 5000
tables:
  users:
    description: "One row per login account"
    columns:
      password_hash: { hidden: true }
      email:         { sensitive: high }

命令

命令	功能
pgmoat <postgres-url>	使用安全默认值启动（无需配置文件）
pgmoat init	根据数据库创建 pgmoat.yaml
pgmoat start	根据 pgmoat.yaml 启动 MCP 服务
pgmoat validate	根据架构和数据库检查 pgmoat.yaml
pgmoat doctor	检查数据库角色是否具有不安全的权限
pgmoat audit verify	验证审计日志哈希链
pgmoat schema-export	将可见架构写入 Markdown 文件

运行 pgmoat --help 查看所有选项。

pgmoat 不会做什么

• 它无法阻止提示词注入。 它会移除写入路径、隐藏你标记为隐藏的内容，并将返回的数据标记为不可信；但如果 Agent 还拥有其他工具（如网络访问、电子邮件），仍可能受骗，将可读取的数据发送到别处。
• 它不能替代 Postgres 权限。 最强有力的控制措施是使用专用角色，并且只授予其所需权限。
• 它无法保证 RLS 策略正确。 它会设置策略读取的会话变量。策略本身有缺陷，仍然会有缺陷。
• 它无法保证在故障期间将审计日志送达远程目标。 它会缓冲、发出警报并记录丢弃情况。

Docker

docker run -i --rm \
  -e PGMOAT_DATABASE_URL="postgresql://readonly_user:[email protected]:5432/mydb" \
  ghcr.io/kitalon-labs-llc/pgmoat:latest

贡献

请参阅 CONTRIBUTING.md。如需报告漏洞，请按照 SECURITY.md 中的说明私下提交。

链接

• 文档：https://kitalonlabs.com/pgmoat/docs
• 源代码和问题反馈：https://github.com/Kitalon-Labs-LLC/pgmoat
• 安全问题报告：[email protected]

许可证

MIT (c) 2026 Kitalon Labs