Multi Cluster Kubernetes MCP Server

多集群 Kubernetes MCP 服务

用于同时管理多个 Kubernetes 集群的 MCP（Model Context Protocol）服务。提供 60+ 个工具，涵盖集群操作、资源管理、监控、RBAC、存储、网络等，可通过 Claude Desktop 等 AI 助手访问。

快速开始

通过 Smithery 安装

npx -y @smithery/cli install @razvanmacovei/k8s-multicluster-mcp --client claude

手动安装

git clone https://github.com/razvanmacovei/k8s-multicluster-mcp.git
cd k8s-multicluster-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 app.py

Docker

docker build -t k8s-mcp .
docker run -v ~/.kube:/root/.kube k8s-mcp

配置

Claude Desktop / MCP 客户端

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "kubernetes": {
      "command": "python3",
      "args": ["/path/to/k8s-multicluster-mcp/app.py"],
      "env": {
        "KUBECONFIG_DIR": "/path/to/your/kubeconfigs"
      }
    }
  }
}

环境变量

变量	默认值	描述
KUBECONFIG_DIR	~/.kube	包含 kubeconfig 文件的目录。每个文件可包含一个或多个上下文。

将 kubeconfig 文件放入配置的目录中。服务会自动发现所有文件中的所有上下文。

先决条件

• Python 3.11 或更高版本
• 一个或多个包含有效集群凭据的 kubeconfig 文件
• 集群中已安装 metrics-server，供 k8s_top_* 和 k8s_cluster_info 工具使用

多集群管理

此服务专为管理多个 Kubernetes 集群而设计：

• 自动发现：扫描 KUBECONFIG_DIR 中的所有 kubeconfig 文件并汇总上下文
• 名称部分匹配：使用 prod 代替 arn:aws:eks:us-east-1:123456:cluster/prod-cluster
• 跨集群操作：比较不同集群中的资源、健康状况和配置
• 上下文缓存：高效的 30 秒 TTL 缓存可避免每次调用时重新读取 kubeconfig 文件
• 集中管理：通过单一界面管理开发、预发布和生产环境

工具参考（60+ 个工具）

集群与上下文管理（6 个工具）

工具	描述
k8s_get_contexts	列出所有 kubeconfig 文件中的可用上下文
k8s_get_namespaces	列出集群中的所有命名空间
k8s_create_ns	创建带可选标签/注释的新命名空间
k8s_delete_ns	删除命名空间（保护系统命名空间）
k8s_get_nodes	列出所有节点及其状态、角色、容量和版本
k8s_cluster_info	全面的集群健康状况摘要（节点、Pod、部署、警告）

资源发现与检查（7 个工具）

工具	描述
k8s_get_resources	列出任意类型的资源（Pod、部署、服务、Ingress 等）
k8s_get_resource	获取单个资源的完整定义
k8s_get_pod_logs	获取 Pod 日志，支持按持续时间筛选和选择容器
k8s_get_events	列出命名空间中的集群事件，并按最近时间排序
k8s_describe	提供类似于 kubectl describe 的详细资源描述
k8s_apis	列出集群中所有可用的 API 组和资源
k8s_crds	列出所有自定义资源定义及其版本和作用域

指标与监控（3 个工具）

工具	描述
k8s_top_nodes	显示节点的 CPU/内存使用量及容量
k8s_top_pods	显示 Pod/容器的 CPU/内存使用量
k8s_diagnose_application	全面的应用诊断，包含问题检测和建议

发布管理（6 个工具）

工具	描述
k8s_rollout_status	获取 deployment/statefulset/daemonset 的发布状态
k8s_rollout_history	获取修订历史
k8s_rollout_undo	回滚到之前的修订版本
k8s_rollout_restart	触发滚动重启
k8s_rollout_pause	暂停正在进行的发布
k8s_rollout_resume	恢复已暂停的发布

扩缩容（3 个工具）

工具	描述
k8s_scale_resource	将 deployment/statefulset/replicaset 扩缩容至 N 个副本
k8s_autoscale_resource	配置水平 Pod 自动扩缩器（HPA）
k8s_update_resources	更新容器的 CPU/内存 requests 和 limits

资源 CRUD（6 个工具）

工具	描述
k8s_create_resource	根据 YAML/JSON 内容创建资源
k8s_apply_resource	应用配置（创建或更新，类似于 kubectl apply）
k8s_delete_resource	删除任意类型的资源，可选强制删除/宽限期
k8s_patch_resource	使用战略合并补丁更新特定字段
k8s_label_resource	为资源添加或更新标签
k8s_annotate_resource	为资源添加或更新注解

工作负载管理（3 个工具）

工具	描述
k8s_expose_resource	将 deployment/pod 暴露为新的 Service
k8s_run_pod	使用指定镜像创建并运行 Pod
k8s_set_resources_for_container	设置容器的资源 limits/requests

节点管理（5 个工具）

工具	描述
k8s_cordon_node	将节点标记为不可调度
k8s_uncordon_node	将节点标记为可调度
k8s_drain_node	通过驱逐 Pod 排空节点（用于维护）
k8s_taint_node	为节点添加污点
k8s_untaint_node	移除节点污点

Pod 操作（1 个工具）

工具	描述
k8s_pod_exec	在容器中执行命令（支持带引号的参数）

Secrets 和 ConfigMap（6 个工具）

工具	描述
k8s_list_secret	列出 Secrets 及其元数据（出于安全考虑隐藏值）
k8s_get_secret_detail	获取 Secret；可选择解码值
k8s_create_secret_resource	创建新的 Secret（自动对值进行 base64 编码）
k8s_list_configmap	列出 ConfigMap 及其键名
k8s_get_configmap_detail	获取包含完整数据内容的 ConfigMap
k8s_create_configmap_resource	创建新的 ConfigMap

RBAC（5 个工具）

工具	描述
k8s_get_roles	列出包含权限规则的 RBAC Roles
k8s_get_clusterroles	列出 RBAC ClusterRoles
k8s_get_rolebindings	列出 RoleBindings（谁拥有何种角色）
k8s_get_clusterrolebindings	列出 ClusterRoleBindings
k8s_get_service_accounts	列出 ServiceAccounts

存储（3 个工具）

工具	描述
k8s_get_pvcs	列出 PersistentVolumeClaims 及其状态、容量和存储类
k8s_get_pvs	列出 PersistentVolumes 及其容量和绑定的声明
k8s_get_storage_classes	列出 StorageClasses 及其供应器和默认状态

网络（1 个工具）

工具	描述
k8s_get_network_policies	列出 NetworkPolicies 及其 Pod 选择器和规则数量

Job 管理（2 个工具）

工具	描述
k8s_get_jobs	列出 Jobs 及其完成状态和用时
k8s_get_cronjobs	列出 CronJobs 及其计划、挂起状态和上次运行时间

使用示例

集群健康检查

Give me a health overview of my production cluster.

多集群对比

Compare the number of pods running in the 'backend' namespace between my 'prod' and 'staging' contexts.

诊断应用问题

My deployment 'my-app' in the 'production' namespace is having issues. Can you diagnose what's wrong?

扩缩容资源

Scale the 'backend' deployment in the 'default' namespace to 5 replicas.

资源管理

Delete the failed job 'data-migration-v1' in the 'batch' namespace.

Create a new namespace called 'staging' with the label environment=staging.

Secret 管理

List all secrets in the 'production' namespace and show me the keys in the 'api-credentials' secret.

RBAC 检查

Show me all role bindings in the 'default' namespace -- who has access to what?

存储概览

List all PVCs in the cluster and show which ones are Pending.

节点维护

Cordon node 'worker-3', drain it ignoring DaemonSets, then uncordon when maintenance is complete.

回滚 Deployment

Roll back the 'api-gateway' deployment in the 'services' namespace to the previous version.

在 Pod 中执行命令

Run 'ls -la /app/config' inside the 'app' container of pod 'web-app-xyz' in the 'default' namespace.

创建资源

Create a new deployment with this YAML:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.27
        ports:
        - containerPort: 80

架构

k8s-multicluster-mcp/
├── app.py                          # MCP server entry point & tool registration
├── src/
│   ├── utils/
│   │   ├── k8s_client.py           # Multi-cluster client with context caching
│   │   └── pluralize.py            # Kubernetes resource kind pluralization
│   └── tools/
│       ├── contexts.py             # Context listing
│       ├── namespaces.py           # Namespace listing
│       ├── namespace_management.py # Namespace create/delete
│       ├── nodes.py                # Node listing
│       ├── pods.py                 # Resource listing & pod logs
│       ├── resources.py            # Single resource retrieval
│       ├── events.py               # Event listing
│       ├── describe.py             # kubectl describe equivalent
│       ├── api_discovery.py        # API & CRD discovery
│       ├── metrics.py              # Node/pod metrics (top)
│       ├── diagnosis.py            # Application diagnostics
│       ├── cluster_health.py       # Cluster health summary
│       ├── rollouts.py             # Rollout management
│       ├── scaling.py              # Scale & autoscale & resource updates
│       ├── resource_management.py  # Create, apply, patch, label, annotate
│       ├── delete_resource.py      # Resource deletion
│       ├── workload_management.py  # Expose, run pod, set resources
│       ├── node_management.py      # Cordon, drain, taint
│       ├── pod_operations.py       # Exec into pods
│       ├── secret_configmap.py     # Secret & ConfigMap management
│       ├── rbac.py                 # Roles, bindings, service accounts
│       ├── storage_network.py      # PVC, PV, StorageClass, NetworkPolicy
│       └── job_management.py       # Jobs & CronJobs
├── requirements.txt
├── pyproject.toml
├── Dockerfile
└── smithery.yaml

v2.0.0 版本更新

• 新增 20 多种工具：删除资源、管理命名空间、管理密钥和 configmap、检查 RBAC、查看存储和网络状态、管理作业、汇总集群健康状况、创建 Pod
• 修复缺陷：修复资源复数形式错误（例如，Ingress -> ingresses，而不是 ingresss）；修复 Pod exec 命令拆分，使其能够处理带引号的参数；修复超时参数处理
• 性能优化：上下文发现现在使用 30 秒 TTL 缓存，并直接将上下文映射到文件，从而避免冗余的文件扫描
• 改进工具描述：所有 60 多种工具都提供了详细描述，以便更好地集成 AI 助手
• 清理依赖项：移除了未使用的 fastapi 和 uvicorn 依赖项
• 安全性：删除命名空间时会保护系统命名空间；默认隐藏密钥值

贡献

欢迎贡献！欢迎提交 Pull Request。