pgops

pgops-mcp

让 AI 助手操作你的 PostgreSQL 数据库，同时避免它搞砸一切。

将 Claude、Cursor 或 VS Code 连接到数据库，然后用日常语言提问。你的助手会获得 18 个工具，用于检查架构、运行查询、诊断慢查询和规划迁移。但它不能悄悄销毁你的数据。

实际效果

以下所有数字都来自此仓库中的演示数据库，数据量为 120 万行， 114 MB。

**你：**我想为 orders.status 创建索引

助手：（调用 migration.plan）

CREATE INDEX "idx_orders_status" ON "orders" (status)
  risk=medium   estimate=4000ms   confidence=medium
  blocks:  writes yes, reads no
  SAFER:   CREATE INDEX CONCURRENTLY "idx_orders_status" ON "orders" (status)

**助手：**普通索引构建会阻塞写入大约 4 秒。CONCURRENTLY 整体耗时更长，但能让写入继续进行。你想选哪种？

该工具不会返回原始计划让模型自行解读，而是返回判断结果、 带有可信度说明的耗时估算，以及更安全的替代方案。

query.explain 的工作方式也一样。它不会直接返回 JSON，而是会给出类似这样的内容：

planner overestimated rows by 5833x (estimated 239,160, actual 40)
  -> run ANALYZE; if it persists the columns may be correlated, consider CREATE STATISTICS

当操作确实很危险时

**你：**清空 orders 表

助手：（调用 query.write，执行 DELETE FROM orders）

CONFIRMATION_REQUIRED
DELETE has no WHERE clause and would affect every row in the table

如果你的客户端支持，审批提示会发送给你，而不是助手。在真人作出答复之前，不会执行任何操作；无论你是否批准，拒绝操作都会写入审计日志。

这才是重点。**助手无法批准自己的危险操作，因为被询问的对象不是它。**如果客户端无法显示提示，系统会降级为使用仅对该确切语句有效的一次性令牌，而不会将其设为“允许”。

为什么要开发它

大多数 Postgres MCP 服务都只是简单的查询封装：检查和 SELECT。没有一个能通过锁影响分析处理迁移，没有一个能根据 EXPLAIN 和 pg_stat_statements 诊断性能问题，也没有一个了解数据库运行所在的容器。如今操作数据库的 Agent 都是在盲目行事，而且缺少安全防护。

pgops-mcp 是一个运维大脑：架构智能 → 受保护的查询 → 迁移引擎 → 性能诊断 → 环境感知，并采用安全架构，让每种操作都可分类、可确认、可审计。

**原生 AI/ML 扩展支持：**由于 pgops 基于 Postgres 核心目录构建，而非脆弱的正则表达式解析，因此原生支持 pgvector 等自定义类型和扩展。migration.plan 和 query.explain 等工具开箱即懂向量类型（vector(384)）和 hnsw 索引，无需任何配置。

初次使用？docs/GETTING_STARTED.md 是一份 15 分钟的引导教程，无需具备 MCP 相关知识。

工具概览

分组	工具
架构	schema.inspect
查询	query.read、query.write（受保护）、query.explain（解析后的计划 + 判断结果）
性能	index.advise、db.health
迁移	migration.plan（试运行 + 锁分析）、migration.describe（通俗解释）、migration.apply、migration.rollback、migration.history
环境	env.topology、env.correlate、container.logs、container.stats
受限	container.restart、container.exec

* 只有服务使用 --approval-mode 运行时才会注册这些工具；即便如此，每次调用仍需确认令牌。container.exec 还会强制执行只读诊断命令允许列表，不提供 Shell。Docker 套接字在主机上等同于 root 权限，因此默认仅提供只读访问。

安全模型（核心优势）

• 将只读和读写连接角色分开；工具绑定到正确的角色
• 执行前对语句进行分类——阻止不带范围限制的 DELETE/UPDATE
• 破坏性操作需要明确的确认令牌
• 每条已执行语句都会连同耗时和判断结果写入只追加的审计日志
• 按超时级别取消失控查询

MCP 接口

原语	内容
工具	17 个——架构、查询、解释、建议、迁移、环境
资源	pgops://schema、schema/summary、schema/{table}、health、migrations、audit/recent、config
提示词	diagnose-slow-query、plan-safe-migration、incident-triage、review-index-health、explain-safety-model
征询	危险操作会直接询问用户，而非通过 Agent；确认令牌是后备方案
采样	migration.describe 使用你的模型将英文转换为计划——此服务不附带 API 密钥
补全	为 pgops://schema/{table} 自动补全表名
进度 / 日志记录	长时间操作期间尽力发送通知

远程访问与 Agent 令牌

stdio 无需身份验证——服务是由客户端启动的子进程，不会开放端口。 HTTP 则需要身份验证，因此没有密钥时服务会拒绝启动：

pgops-mcp keygen                                    # RS256 keypair
pgops-mcp issue-token --subject my-agent            # read-only by default
pgops-mcp issue-token --subject deploy-bot --scope pgops:read --scope pgops:write
pgops-mcp scopes                                    # which scope each tool needs

pgops-mcp --transport http --public-key ~/.pgops/keys/pgops_public.pem

服务仅持有公钥，因此可以验证令牌，但无法签发令牌。 作用域（pgops:read / pgops:write / pgops:admin）与防护措施采用相同的危险等级；未列出作用域的工具需要 admin——默认拒绝。除非另有指定，否则服务会绑定到环回地址。

安装

pgops-mcp 是 MCP 服务，而不是 Python 库——其中没有任何内容 предназначено 用于导入，且 pgops.* 不承诺 API 稳定性。安装方式与安装任何 MCP 服务相同：让客户端连接到它。

Claude Desktop / Cursor / VS Code：

{
  "mcpServers": {
    "pgops": {
      "command": "uvx",
      "args": ["pgops-mcp"],
      "env": { "PGOPS_DSN": "postgresql://user:pass@localhost:5432/mydb" }
    }
  }
}

uvx 会在临时环境中获取并运行它——无需预先安装，也不会将任何内容添加到你自己的项目依赖项中。

或者运行容器，如果你不想在连接数据库的机器上安装 Python 工具链：

{
  "mcpServers": {
    "pgops": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PGOPS_DSN",
        "-v", "pgops-audit:/var/lib/pgops",
        "ghcr.io/arzharch/pgops-mcp:latest"
      ],
      "env": { "PGOPS_DSN": "postgresql://user:[email protected]:5432/mydb" }
    }
  }
}

容器会带来两点变化：在 /var/lib/pgops 挂载卷，否则审计日志会随容器一起消失；容器内的 localhost 指向容器自身——请使用 host.docker.internal 或 compose 服务名称。

在将客户端连接到它之前，先检查连接：

uvx pgops-mcp --selfcheck --dsn "postgresql://user:pass@localhost:5432/mydb"

这两种方式安装的是同一个服务，并一同列在 MCP Registry 条目中——它们会让不同的人遇到问题。uvx 无需预装任何内容，但假设主机可以运行 Python；容器则只要求安装 Docker。

配置、HTTP 传输、Agent 令牌和故障排除，请参阅 SETUP.md；从源代码检出版本运行，请参阅 CONTRIBUTING.md。

文档

链接使用绝对路径，因此从 PyPI 项目页面和 GitHub 均可访问。

使用指南

文档	内容
入门指南	前 15 分钟，无需具备 MCP 知识
工具参考	全部 18 个工具：参数、返回值、错误代码、作用范围
设置与配置	客户端、HTTP 身份验证、可观测性、故障排除
环境变量	每个配置项均有说明
安全模型	可执行的操作、拒绝的操作、已知限制
更新日志	每个版本的变更内容

工作原理

文档	内容
架构	系统设计与权衡
系统设计	安全防护流程，附有图示
决策记录	每项选择的原因及其代价
基准测试	测量内容及对比对象

参与贡献

文档	内容
贡献指南	源码检出、检查门槛、发布流程
模块布局	各模块的用途

验证方式

471 项测试，其中重要测试会在容器中的真实 PostgreSQL 16 上运行，而不是使用模拟对象。这是经过深思熟虑的决定（ADR-005）：只在假对象上验证过的防护措施，验证的对象并不正确。那些值得关注的故障——default_transaction_read_only、锁升级、事务性 DDL、重写时的 relfilenode 变更——都是实际数据库的行为。

测试套件	验证内容
防护措施与分类器	针对运行中的 Postgres，验证每条拒绝规则
基于属性的测试（Hypothesis）	针对无人想到要编写的输入，验证不变量本身
红队测试	恶意 Agent 可能尝试的 15 种指定攻击——每种都被拒绝并记录审计日志
实时服务	真实 HTTP 服务、真实 JWT、端到端测试
基准测试	将延迟预算用作回归预警，并作为 CI 工件发布

红队测试套件曾发现真实漏洞，这正是需要它的理由：它发现某条被拒绝的语句签发的确认令牌，竟可用于另一条语句；还发现带有 pgops:read 作用域的令牌可以调用 query.write，因为作用域表只写在文档中，并未强制执行。

已知限制

在此明确列出，而不是留待用户自行发现：

• 不支持按会话隔离数据库。 身份验证可识别调用者，作用域会限制其可执行的操作，但所有调用者共用一个连接管理器和一份审计日志。该工具适用于一位工程师和少数几个数据库，不适用于多租户 SaaS。
• index.advise 会指出发生顺序扫描的表，而不是需要创建索引的列——这需要逐条语句检查执行计划。它会明确说明这一点，而不是凭空编造 CREATE INDEX。
• DROP INDEX / DROP CONSTRAINT 无法回滚，因为删除前不会捕获对象定义。回滚操作会拒绝执行并说明原因，而不是猜测并重建对象。

以下是针对 120 万行的 orders 表进行类型变更时，migration.plan 的返回示例：

ALTER TABLE "orders" ALTER COLUMN "total_cents" TYPE bigint
  op=table_rewrite  risk=high  estimate=4800ms  confidence=medium
  why:   rewrites every row and rebuilds every index, holding AccessExclusiveLock
  SAFER: add a new column of the target type, backfill in batches, sync with a
         trigger, swap the names, then drop the old column

无需自备数据库即可试用

已预置数据的技术栈，包含上述每个示例中使用的 120 万行 orders 表。主机端口为 5435，因此不会与本地运行在 5432 端口的 Postgres 冲突：

git clone https://github.com/arzharch/pgops-mcp && cd pgops-mcp
docker compose up -d
uvx pgops-mcp --selfcheck --dsn "postgresql://pgops:pgops_dev@localhost:5435/pgops_demo"

---

采用 MIT 许可证。欢迎贡献——请参阅 CONTRIBUTING.md。