mcp-percona-pg

mcp-percona-pg

一个面向 Percona Operator for PostgreSQL 的 Model Context Protocol 服务。它让支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor 等）能够在 Kubernetes 上操作 PostgreSQL + PgBouncer 集群——包括拓扑、连接池、调优、备份/PITR、灾难恢复、扩展和生命周期管理，所有行为均由标志控制。

它通过你的 kube-config 操作 Operator 的自定义资源（PerconaPGCluster、PerconaPGBackup、PerconaPGRestore、PerconaPGUpgrade），让模型按你熟悉的方式工作：“将 dev-pg 扩容到 3 个副本”“将连接池模式切换为事务模式”“将 prod-pg 恢复到 UTC 时间 12:00”。

默认安全：服务以只读模式启动，可将作用范围限制为允许列表中的命名空间和集群，并防止对关键集群进行修改；恢复、升级和删除操作分别需要单独启用，高影响操作还需输入确认内容。它绝不会读取或返回数据库凭据。

功能

• 发现与状态 — 列出集群、查看各集群摘要和原始 .status（Patroni 成员、PostgreSQL/PgBouncer 就绪状态）、连接端点、备份和恢复记录。
• 连接池 — 读取并更新 PgBouncer pool_mode 和全局连接池参数（default_pool_size、max_client_conn 等）。
• PostgreSQL 调优 — 通过 spec.patroni.dynamicConfiguration 读取/合并参数（唯一安全的 Patroni 操作路径）。
• 生命周期管理 — 扩缩 PostgreSQL/PgBouncer、暂停/恢复、切换内置扩展、按需备份。
• 灾难恢复与恢复 — 恢复/时间点恢复、提升备用节点、升级主版本——每项操作均需单独启用。

安全模型

层级	标志	作用
访问模式	PERCONA_MODE	read-only → read-write → admin；不会注册权限过高的工具
命名空间/集群允许列表	PERCONA_NAMESPACE_ALLOWLIST、PERCONA_CLUSTER_ALLOWLIST	限定 Agent 可操作的范围
受保护的集群	PERCONA_PROTECTED_CLUSTERS	可读取，但绝不修改、恢复或删除
恢复 / 升级 / 删除	PERCONA_ALLOW_RESTORE、PERCONA_ALLOW_UPGRADE、PERCONA_ALLOW_DELETE	在 admin 模式基础上分别单独启用
确认	PERCONA_REQUIRE_CONFIRMATION	高影响操作需要回显集群名称
演练 / 审计	PERCONA_DRY_RUN、PERCONA_AUDIT_LOG	仅验证；每项受保护操作均记录一行 JSON 审计日志
交互式确认	（自动）	执行破坏性和高影响操作前，会通过 MCP elicitation 提示用户批准；如果客户端不支持 elicitation，则回退到 PERCONA_ALLOW_* 开关

工具

读取（read-only 及以上）：list_contexts、list_clusters、get_cluster、get_cluster_status、get_connection_info、get_pgbouncer_config、get_pg_parameters、list_backups、list_restores

写入（read-write 及以上）：scale_cluster、set_pgbouncer_config、set_pg_parameters、pause_cluster、toggle_builtin_extension、create_backup

管理（admin）：restore_cluster（需要 PERCONA_ALLOW_RESTORE）、upgrade_cluster（需要 PERCONA_ALLOW_UPGRADE）、promote_standby、delete_backup / delete_cluster（需要 PERCONA_ALLOW_DELETE）

快速开始 — 添加到你的 Agent

已发布到 npm，包名为 @dockndevai/mcp-percona-pg。无需克隆或构建 — MCP 客户端会按需通过 npx 运行它。请从 read-only 模式开始；所有变量请参阅 .env.example，各客户端的完整指南请参阅 docs/CLIENTS.md。

Claude Code（命令行）

claude mcp add percona-pg -e PERCONA_MODE="read-only" -e PERCONA_NAMESPACE="postgres-operator" -- npx -y @dockndevai/mcp-percona-pg

Claude Desktop · Cursor · Windsurf — 将相同代码块添加到 claude_desktop_config.json、.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json 中：

{
  "mcpServers": {
    "percona-pg": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-percona-pg"],
      "env": {
        "PERCONA_MODE": "read-only",
        "PERCONA_NAMESPACE": "postgres-operator"
      }
    }
  }
}

OpenAI Codex CLI — 在 ~/.codex/config.toml 中：

[mcp_servers.percona-pg]
command = "npx"
args = ["-y", "@dockndevai/mcp-percona-pg"]
env = { PERCONA_MODE = "read-only", PERCONA_NAMESPACE = "postgres-operator" }

示例提示词

• “列出 PostgreSQL 集群，并告诉我 dev-pg 的状态。”
• “dev-pg 使用的 pool_mode 是什么？默认池有多大？” → get_pgbouncer_config
• “将 dev-pg PgBouncer 设置为事务池化，并将 default_pool_size 设为 25。”（需要 read-write）
• “将 dev-pg 上的 shared_buffers 增加到 512MB。”（需要 read-write）
• “将 dev-pg 完整备份到 repo1。”（需要 read-write）
• “将 dev-pg 恢复到 2026-08-30 12:00:00+00。”（需要 admin + PERCONA_ALLOW_RESTORE + 确认）

前提条件

• 正在运行 Percona Operator for PostgreSQL v2（pgv2.percona.com/v2）的 Kubernetes 集群。
• 服务可读取的 kube-config。为确保安全，请使用 ServiceAccount/RBAC，将权限限定在 Operator 的命名空间以及你希望 Agent 查看其内容的 pgv2.percona.com 资源范围内。

从源代码运行（开发）

建议使用上方发布的包。若要从克隆的仓库运行：

npm install
npm run build
node dist/index.js   # with the environment variables set

开发

npm run dev
npm test          # security policy + annotations
npm run typecheck

发布

此服务为官方 MCP 注册表提供 server.json，并提供用于 npm 所有权验证的 mcpName。请参阅 PUBLISHING.md。

许可证

MIT