dockndevai/mcp-percona-pg

A Model Context Protocol server for the **Percona Operator for PostgreSQL**. It lets an MCP-capable client (Claude Desktop, Claude Code, Cursor, …) **operate PostgreSQL + PgBouncer clusters on Kubernetes** — topology, connection pooling, tuning, backups/PITR, DR, extensions, and lifecycle — with behaviour controlled entirely by flags.
It drives the operator's custom resources (PerconaPGCluster, PerconaPGBackup, PerconaPGRestore, PerconaPGUpgrade) through your kube-config, so the model works the way you already do: *"scale dev-pg to 3 replicas"*, *"switch pooling to transaction mode"*, *"restore prod-pg to 12:00 UTC"*.
Safe by default: it starts **read-only**, can be scoped to an allowlist of namespaces and clusters, protects critical clusters from mutation, gates restore / upgrade / delete behind separate opt-ins, and requires typed confirmation for high-impact actions. It never reads or returns database credentials.
Features
- **Discovery & status** — list clusters, per-cluster summary and raw .status (Patroni members, PostgreSQL/PgBouncer readiness), connection endpoints, backups and restores.
- **Connection pooling** — read and update PgBouncer pool_mode and the global pool tunables (default_pool_size, max_client_conn, …).
- **PostgreSQL tuning** — read/merge parameters via spec.patroni.dynamicConfiguration (the only Patroni-safe path).
- **Lifecycle** — scale PostgreSQL/PgBouncer, pause/resume, toggle built-in extensions, on-demand backups.
- **DR & recovery** — restore / point-in-time recovery, promote a standby, major-version upgrades — each individually gated.
Security model
| Layer | Flag | Effect |
|---|---|---|
| Access mode | PERCONA_MODE | read-only → read-write → admin; over-privileged tools are never registered |
| Namespace/cluster allowlists | PERCONA_NAMESPACE_ALLOWLIST, PERCONA_CLUSTER_ALLOWLIST | scope what the agent can touch |
| Protected clusters | PERCONA_PROTECTED_CLUSTERS | readable, never mutated/restored/deleted |
| Restore / upgrade / delete | PERCONA_ALLOW_RESTORE, PERCONA_ALLOW_UPGRADE, PERCONA_ALLOW_DELETE | separate opt-ins on top of admin mode |
| Confirmation | PERCONA_REQUIRE_CONFIRMATION | high-impact ops require echoing the cluster name |
| Dry-run / audit | PERCONA_DRY_RUN, PERCONA_AUDIT_LOG | validate-only; JSON audit line per guarded op |
| Interactive confirmation | *(automatic)* | destructive & high-impact ops prompt the human to approve via MCP elicitation before running; fall back to the PERCONA_ALLOW_* gates when the client can't elicit |
Tools
**Read** (read-only+): list_contexts, list_clusters, get_cluster, get_cluster_status, get_connection_info, get_pgbouncer_config, get_pg_parameters, list_backups, list_restores
**Write** (read-write+): scale_cluster, set_pgbouncer_config, set_pg_parameters, pause_cluster, toggle_builtin_extension, create_backup
**Admin** (admin): restore_cluster (needs PERCONA_ALLOW_RESTORE), upgrade_cluster (needs PERCONA_ALLOW_UPGRADE), promote_standby, delete_backup / delete_cluster (need PERCONA_ALLOW_DELETE)