pgops-mcp

一个生产级 MCP 服务器，为 AI 代理提供安全、可审计、专家级的控制能力， 可操作真实的 PostgreSQL 数据库及其周围的 Docker 栈——无需 shell 命令， 无需 Python 脚本，只有工具。

为什么

现有的 Postgres MCP 服务器只是轻量的查询包装器：内省 + SELECT。它们都无法处理 带有锁影响分析的迁移，无法从 EXPLAIN + pg_stat_statements 诊断性能，也无法理解 数据库所在的容器化环境。如今操作数据库的代理是在盲目且不安全地飞行。

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

Related MCP server: PostgreSQL MCP Server

工具面（v0.1）

* 除非服务器以 --approval-mode 运行，否则根本不会注册这些工具，即使如此， 每次调用也需要确认令牌。container.exec 还强制使用只读诊断命令白名单——它不提供 shell。Docker 套接字在主机上等同于 root，因此默认是只读访问。

安全模型（核心差异化）

• 分离的只读 / 读写连接角色；工具绑定到正确的角色

• 执行前进行语句分类——无界 DELETE/UPDATE 被阻止

• 破坏性操作需要显式确认令牌

• 每条执行的语句都会记录到追加式审计日志中，包含时间和判定

• 通过超时层级取消失控查询

MCP 表面

远程访问与代理令牌

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——默认拒绝。除非另有说明，否则绑定回环地址。

快速开始

uv sync
# point at your local Postgres in Docker:
export PGOPS_DSN="postgresql://user:pass@localhost:5432/mydb"
uv run pgops-mcp            # stdio transport for Claude Desktop / Cursor / VS Code

添加到 Claude Desktop：

{
  "mcpServers": {
    "pgops": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pgops-mcp", "pgops-mcp"]
    }
  }
}

文档

• docs/PRD.md — 是什么与为什么、目标、非目标

• docs/SPEC.md — 分阶段技术规范，带有硬性门禁

• docs/ARCHITECTURE.md — 系统设计与权衡

• docs/TOOLS.md — 完整工具目录，包含模式与示例

• docs/adr/ — 架构决策记录

• docs/flow.md — 实时进度日志

• docs/interview_prep.md — 不断增长的面试问答

状态

阶段 0–6b 已完成（319 个测试，每个防护、判定和锁影响规则都通过 testcontainers 针对真实 Postgres 验证——没有模拟——还有端到端套件，通过 stdio 和经过认证的 HTTP 服务器将服务器作为真正的 MCP 子进程驱动）。

migration.rollback 故意保持开放——参见 docs/TOOLS.md。

migration.plan 对 120 万行 orders 表进行类型更改时返回的示例：

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

快速启动开发数据库（主机端口 5433，以避免与本地 5432 端口上的 Postgres 冲突）：

docker compose up -d
export PGOPS_DSN="postgresql://pgops:pgops_dev@localhost:5433/pgops_demo"
uv run pgops-mcp --selfcheck