CloudNativePG MCP 服务器

一个用于通过 CloudNativePG 操作符管理 PostgreSQL 集群的 MCP 服务器。

此版本使用 MCP Base 脚手架作为其服务器布局、身份验证、容器构建、Helm 图表、提示词注册表和测试工具。之前的手动实现保留在 deprecated-v1/ 下以供参考。

工具接口

该服务器公开了来自 v1 实现的 CloudNativePG 工具：

• list_postgres_clusters

• get_cluster_status

• create_postgres_cluster

• scale_postgres_cluster

• delete_postgres_cluster

• list_postgres_roles

• create_postgres_role

• update_postgres_role

• delete_postgres_role

• list_postgres_databases

• create_postgres_database

• delete_postgres_database

它还包括用于提示词管理的 MCP Base 脚手架管理工具：

• admin_reload_prompts

• admin_get_prompt_manifest

Related MCP server: PostgreSQL MCP Server

布局

• src/cnpg_mcp_server.py: 生产环境 FastMCP HTTP 入口点

• src/cnpg_mcp_test_server.py: 无认证/OIDC 测试入口点

• src/cnpg_mcp_tools.py: CloudNativePG 工具实现与注册

• src/mcp_context.py: 带有用户身份提取的 MCP 上下文包装器

• src/auth_*.py: MCP Base 脚手架身份验证支持

• chart/: Helm 部署资产

• test/: MCP 插件测试工具

• SCAFFOLD_INVENTORY.md: MCP Base 脚手架工件哈希值

开发

创建环境并安装依赖项：

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

运行脚手架注册冒烟测试：

python bin/smoke_test.py

运行本地无认证 MCP 测试套件：

python test/run-local-tests.py

运行从 deprecated-v1/test/plugins 适配而来的 CloudNativePG Kubernetes 集成测试：

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

这些测试会创建、扩展、更新和删除真实的 CloudNativePG 资源。有用的可选设置：

• CNPG_MCP_TEST_NAMESPACE: 测试资源的命名空间

• CNPG_MCP_TEST_CLUSTER_PREFIX: 生成的集群名称前缀

• CNPG_MCP_TEST_STORAGE_SIZE: 每个实例的存储大小，默认为 1Gi

• CNPG_MCP_TEST_CREATE_WAIT_SECONDS: 集群就绪超时时间，默认为 300

• CNPG_MCP_TEST_SCALE_WAIT_SECONDS: 扩展就绪超时时间，默认为 300

本地运行

脚手架入口点使用 HTTP 传输：

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

测试服务器可以在没有身份验证的情况下运行：

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

Kubernetes 访问

这些工具使用 Kubernetes Python 客户端。它们按以下顺序加载配置：

1. 集群内服务账户配置

2. 来自 ~/.kube/config 或 KUBECONFIG 的本地 kubeconfig

大多数工具接受一个可选的 namespace 参数。如果省略，则使用当前的 Kubernetes 上下文命名空间，并回退到 default。

对于集群内 Helm 部署，服务器使用部署的服务账户。默认情况下，图表仅在 Helm 发布命名空间中授予该服务账户 CNPG 和 secret 权限。要在另一个命名空间中管理 CNPG 资源，请传递工具的 namespace 参数并授予该服务账户相应的访问权限：

rbac:
  targetNamespaces:
    - application-databases

对于必须在任意命名空间中运行的共享 MCP 部署，请选择集群范围的 RBAC：

rbac:
  clusterWide: true

集群范围模式会授予跨命名空间的 secret 访问权限，因此在已知目标集的情况下，请优先使用显式的 targetNamespaces。

部署

MCP Base 脚手架包含 Docker 和 Helm 资产：

make build
make push
make helm-install

在使用部署目标之前，请使用 python bin/configure-make.py 生成用于镜像和命名空间设置的 make.env。