CloudNativePG MCP Server

An MCP server for managing PostgreSQL clusters through the CloudNativePG operator.

This version uses the MCP Base scaffold for its server layout, authentication, container build, Helm chart, prompt registry, and test harness. The previous manual implementation is retained under deprecated-v1/ for reference.

Tool Surface

The server exposes the CloudNativePG tools from the v1 implementation:

• list_postgres_clusters
• get_cluster_status
• create_postgres_cluster
• scale_postgres_cluster
• configure_projected_volumes
• resize_postgres_cluster
• get_cluster_resize_status
• promote_cluster_instance
• delete_cluster_instance
• delete_postgres_cluster
• list_postgres_roles
• get_postgres_role_status
• create_postgres_role
• update_postgres_role
• delete_postgres_role
• list_postgres_databases
• get_postgres_database_status
• create_postgres_database
• delete_postgres_database

Projected volumes

Secrets and ConfigMaps can be projected into the instance pods, which CloudNativePG mounts under /projected. create_postgres_cluster accepts projected_secrets, projected_config_maps, and projected_default_mode; configure_projected_volumes sets them on an existing cluster.

Rather than requiring a full Kubernetes VolumeProjection, you name the resource and, optionally, the directory it maps to. Every key becomes a file named after the key:

projected_secrets=["db-creds"]              # -> /projected/secret/db-creds/{username,password}
projected_config_maps=["app-config"]        # -> /projected/config/app-config/{ca.crt,settings.ini}
projected_secrets={"db-creds": "db"}        # -> /projected/db/{username,password}
projected_config_maps={"app-config": "conf/app"}

The default directory is secret/<name> or config/<name>, so a Secret and a ConfigMap sharing a name cannot collide. Directories are relative to /projected — CloudNativePG always mounts the template there and the path is not configurable, so an absolute directory is rejected.

projected_default_mode accepts octal strings like "0400" as well as the decimal integers the Kubernetes API stores. Note that CloudNativePG runs instances with fsGroup set, so Kubernetes may add the group-read bit — a requested 0400 typically lands as 0440 on disk.

Kubernetes maps projections per key, not per resource, so each Secret and ConfigMap is read to enumerate its keys. That is a snapshot: keys added to a resource afterwards are not projected until you configure the projection again. The resource must exist when the projection is configured.

Paths are validated up front. Neither the Cluster CRD nor the CloudNativePG webhook rejects an absolute path, a .. element, or two sources claiming the same file — those are only caught later at Pod admission, which surfaces as instances that will not start.

configure_projected_volumes replaces .spec.projectedVolumeTemplate outright rather than merging, so pass the complete desired set each time; clear=True removes it. Changing projected volumes alters the instance pod spec, so CloudNativePG performs a rolling restart to apply it. The current projection is reported by get_cluster_status with detail_level="detailed".

Sources these tools do not build (for example serviceAccountToken or downwardAPI applied out of band) are shown in the read-back output but are replaced if you call configure_projected_volumes.

Storage resize

resize_postgres_cluster changes .spec.storage.size. Growing is applied directly and CloudNativePG expands the volumes in place. Shrinking cannot be applied to an existing volume at all, so the tool only starts a migration and returns immediately — replication can take hours, so no tool call blocks on it.

Starting a shrink (requires confirm_shrink=True) performs three requests: set cnpg.io/validation: disabled, patch the smaller .spec.storage.size together with an increased .spec.instances in a single request so the added instance is created at the new size, then remove the annotation. Validation is restored even if the patch fails; restore_validation_only=True recovers the annotation if a run is interrupted.

The rest of the workflow is driven by separate tools, so you decide when each step happens:

1. get_cluster_resize_status — per-instance volume sizes (requested vs.

actual), which instances still hold the previous size, replication health, and the recommended next action.

1. promote_cluster_instance — switchover to the new, smaller instance by

setting .status.targetPrimary. Refuses instances the operator does not report as healthy unless force=True.

1. delete_cluster_instance — deletes one instance's PVCs and Pod, leaving

.spec.instances alone so the operator rebuilds it from the primary at the current size. Refuses to delete the current primary. Repeat for each instance still on the old size, one at a time.

1. scale_postgres_cluster — return to your original instance count.

Growing needs a storage class with working volume expansion. If get_cluster_resize_status keeps showing requested / actual sizes that differ, the provisioner may advertise allowVolumeExpansion without running a resize controller; the status output points at the PVC events that confirm this.

Roles are managed through CloudNativePG's first-class DatabaseRole CRD rather than the deprecated Cluster .spec.managed.roles field. create_postgres_role creates a DatabaseRole named <cluster>-<role> and, unless disable_password is set, generates a password Secret referenced by the CRD. Beyond the standard role flags (login, superuser, inherit, createdb, createrole, replication, bypassrls) it exposes the CRD's in_roles, connection_limit, valid_until, comment, client_certificate, and reclaim_policy. update_postgres_role patches the CRD spec and can rotate the password Secret; delete_postgres_role deletes the CRD, honoring its reclaim policy, and accepts drop_role=True to force the role to be dropped from PostgreSQL. get_postgres_role_status reports the CRD's current spec values and operator reconciliation status. list_postgres_roles lists DatabaseRole CRDs for a cluster and separately reports any legacy .spec.managed.roles entries still present on the Cluster.

create_postgres_database supports CloudNativePG Database CRD create-time locale options, including encoding, locale, locale_provider, locale_collate, locale_ctype, icu_locale, icu_rules, builtin_locale, and collation_version. get_postgres_database_status reports the current Database CRD spec values for those options along with the operator reconciliation status. create_postgres_cluster accepts container_image to set the CloudNativePG spec.imageName directly; when omitted it continues to derive the image from postgres_version. It also exposes pod scheduling and storage placement controls: storage_class (spec.storage.storageClass), node_selector (spec.affinity.nodeSelector), and tolerations (spec.affinity.tolerations). Together these enable node-local storage: pin instances with node_selector (e.g. {"kubernetes.io/hostname": "worker-1"} for a specific node, or a label like {"disktype": "nvme"} for a pool), select a node-local storage_class, and supply tolerations so pods are admitted onto dedicated (tainted) storage nodes. image_pull_policy maps to spec.imagePullPolicy.

It also includes MCP Base scaffold admin tools for prompt management:

• admin_reload_prompts
• admin_get_prompt_manifest

Layout

• src/cnpg_mcp_server.py: production FastMCP HTTP entrypoint
• src/cnpg_mcp_test_server.py: no-auth/OIDC test entrypoint
• src/cnpg_mcp_tools.py: CloudNativePG tool implementations and registration
• src/mcp_context.py: MCP context wrapper with user identity extraction
• src/auth_*.py: MCP Base scaffold authentication support
• chart/: Helm deployment assets
• test/: MCP plugin test harness
• SCAFFOLD_INVENTORY.md: MCP Base scaffold artifact hashes

Development

Create an environment and install dependencies:

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt -r test/requirements.txt

Run the scaffold registration smoke test:

python bin/smoke_test.py

Run the local no-auth MCP test suite:

python test/run-local-tests.py

Run the CloudNativePG Kubernetes integration tests adapted from deprecated-v1/test/plugins:

python test/run-local-tests.py --include-integration
# or
make test-integration

These tests create, scale, update, and delete real CloudNativePG resources. Useful optional settings:

• CNPG_MCP_TEST_NAMESPACE: namespace for test resources
• CNPG_MCP_TEST_CLUSTER_PREFIX: generated cluster name prefix
• CNPG_MCP_TEST_STORAGE_SIZE: per-instance storage size, default 1Gi
• CNPG_MCP_TEST_CREATE_WAIT_SECONDS: cluster readiness timeout, default 300
• CNPG_MCP_TEST_SCALE_WAIT_SECONDS: scale readiness timeout, default 300

Running Locally

The scaffold entrypoint uses HTTP transport:

python src/cnpg_mcp_server.py --host 0.0.0.0 --port 4200

The test server can be run without authentication:

python src/cnpg_mcp_test_server.py --host 127.0.0.1 --port 4201 --no-auth

Kubernetes Access

The tools use the Kubernetes Python client. They load configuration in this order:

1. In-cluster service account configuration
2. Local kubeconfig from ~/.kube/config or KUBECONFIG

Most tools accept an optional namespace. When omitted, the current Kubernetes context namespace is used, falling back to default.

For in-cluster Helm deployments, the server uses the deployment service account. By default the chart grants that service account CNPG and secret permissions only in the Helm release namespace. To manage CNPG resources in another namespace, pass the tool's namespace argument and grant the service account access there:

rbac:
  targetNamespaces:
    - application-databases

For a shared MCP deployment that must operate in arbitrary namespaces, opt in to cluster-wide RBAC:

rbac:
  clusterWide: true

Cluster-wide mode grants secret access across namespaces, so prefer explicit targetNamespaces when the target set is known.

Deployment

The MCP Base scaffold includes Docker and Helm assets:

make build
make push
make helm-install

Use python bin/configure-make.py to generate make.env for image and namespace settings before using the deployment targets.