{
  "markdown": "# mcp-percona-pg\n\n[![CI](https://github.com/dockndevai/mcp-percona-pg/actions/workflows/ci.yml/badge.svg)](https://github.com/dockndevai/mcp-percona-pg/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![npm](https://img.shields.io/npm/v/@dockndevai/mcp-percona-pg)](https://www.npmjs.com/package/@dockndevai/mcp-percona-pg)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the **[Percona Operator for PostgreSQL](https://docs.percona.com/percona-operator-for-postgresql/2.0/)**. 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.\n\nIt 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\"*.\n\nSafe 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.\n\n## Features\n\n- **Discovery & status** — list clusters, per-cluster summary and raw `.status` (Patroni members, PostgreSQL/PgBouncer readiness), connection endpoints, backups and restores.\n- **Connection pooling** — read and update PgBouncer `pool_mode` and the global pool tunables (`default_pool_size`, `max_client_conn`, …).\n- **PostgreSQL tuning** — read/merge parameters via `spec.patroni.dynamicConfiguration` (the only Patroni-safe path).\n- **Lifecycle** — scale PostgreSQL/PgBouncer, pause/resume, toggle built-in extensions, on-demand backups.\n- **DR & recovery** — restore / point-in-time recovery, promote a standby, major-version upgrades — each individually gated.\n\n## Security model\n\n| Layer | Flag | Effect |\n|---|---|---|\n| Access mode | `PERCONA_MODE` | `read-only` → `read-write` → `admin`; over-privileged tools are never registered |\n| Namespace/cluster allowlists | `PERCONA_NAMESPACE_ALLOWLIST`, `PERCONA_CLUSTER_ALLOWLIST` | scope what the agent can touch |\n| Protected clusters | `PERCONA_PROTECTED_CLUSTERS` | readable, never mutated/restored/deleted |\n| Restore / upgrade / delete | `PERCONA_ALLOW_RESTORE`, `PERCONA_ALLOW_UPGRADE`, `PERCONA_ALLOW_DELETE` | separate opt-ins on top of admin mode |\n| Confirmation | `PERCONA_REQUIRE_CONFIRMATION` | high-impact ops require echoing the cluster name |\n| Dry-run / audit | `PERCONA_DRY_RUN`, `PERCONA_AUDIT_LOG` | validate-only; JSON audit line per guarded op |\n\n## Tools\n\n**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`\n\n**Write** (`read-write`+): `scale_cluster`, `set_pgbouncer_config`, `set_pg_parameters`, `pause_cluster`, `toggle_builtin_extension`, `create_backup`\n\n**Admin** (`admin`): `restore_cluster` (needs `PERCONA_ALLOW_RESTORE`), `upgrade_cluster` (needs `PERCONA_ALLOW_UPGRADE`), `promote_standby`, `delete_backup` / `delete_cluster` (need `PERCONA_ALLOW_DELETE`)\n\n## Quickstart — add to your agent\n\nPublished on npm as [`@dockndevai/mcp-percona-pg`](https://www.npmjs.com/package/@dockndevai/mcp-percona-pg). No clone or build needed — your MCP client runs it on demand with `npx`. **Start in `read-only` mode**; see [`.env.example`](.env.example) for every variable and [docs/CLIENTS.md](docs/CLIENTS.md) for the full per-client guide.\n\n**Claude Code** (CLI)\n\n```bash\nclaude mcp add percona-pg -e PERCONA_MODE=\"read-only\" -e PERCONA_NAMESPACE=\"postgres-operator\" -- npx -y @dockndevai/mcp-percona-pg\n```\n\n**Claude Desktop · Cursor · Windsurf** — same block in `claude_desktop_config.json`, `.cursor/mcp.json`, or `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"percona-pg\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dockndevai/mcp-percona-pg\"],\n      \"env\": {\n        \"PERCONA_MODE\": \"read-only\",\n        \"PERCONA_NAMESPACE\": \"postgres-operator\"\n      }\n    }\n  }\n}\n```\n\n**OpenAI Codex CLI** — in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.percona-pg]\ncommand = \"npx\"\nargs = [\"-y\", \"@dockndevai/mcp-percona-pg\"]\nenv = { PERCONA_MODE = \"read-only\", PERCONA_NAMESPACE = \"postgres-operator\" }\n```\n\n## Example prompts\n\n- *\"List the PostgreSQL clusters and show me the status of `dev-pg`.\"*\n- *\"What pool_mode is `dev-pg` using, and how big is the default pool?\"* → `get_pgbouncer_config`\n- *\"Set `dev-pg` PgBouncer to transaction pooling with default_pool_size 25.\"* (needs `read-write`)\n- *\"Bump `shared_buffers` to 512MB on `dev-pg`.\"* (needs `read-write`)\n- *\"Take a full backup of `dev-pg` to repo1.\"* (needs `read-write`)\n- *\"Restore `dev-pg` to 2026-08-30 12:00:00+00.\"* (needs `admin` + `PERCONA_ALLOW_RESTORE` + confirmation)\n\n## Prerequisites\n\n- A Kubernetes cluster running the **Percona Operator for PostgreSQL v2** (`pgv2.percona.com/v2`).\n- A kube-config the server can read. For safety, use a ServiceAccount/RBAC scoped to the operator's namespaces and to the `pgv2.percona.com` resources you want the agent to see.\n\n## Run from source (development)\n\nPrefer the published package above. To run from a clone:\n\n```bash\nnpm install\nnpm run build\nnode dist/index.js   # with the environment variables set\n```\n\n## Develop\n\n```bash\nnpm run dev\nnpm test          # security policy + annotations\nnpm run typecheck\n```\n\n## Publishing\n\nThis server ships a [`server.json`](server.json) for the official MCP registry and an [`mcpName`](package.json) for npm ownership validation. See **[PUBLISHING.md](PUBLISHING.md)**.\n\n## License\n\nMIT\n",
  "bytes": 5934,
  "sha": "33e15189f73f6917868e664ce6282d00a5e242fc11ed62823790576a3351c47b",
  "repo_slug": "dockndevai/mcp-percona-pg",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dockndevai_mcp_percona_pg_7164995a/readme"
}