KubeStellar MCP

kubestellar-mcp

面向 Claude Code 的 AI 驱动型多集群 Kubernetes 工具。

以单集群的使用体验，应对多集群的现实——操作你的应用，而不是你的集群。

为什么选择 KubeStellar

kubestellar-mcp 是通往 KubeStellar 平台的 AI 入口——一个用于多集群 Kubernetes 编排的 CNCF Sandbox 生态系统。

子项目	角色
kubestellar	核心引擎——BindingPolicy、WDS、ITS、WEC 工作负载传播
console	Web 仪表板——300 多张卡片、AI 任务、GPU 和 LLM-d 监控
console-marketplace	153 多个社区卡片预设（GPU/AI/ML、ArgoCD、OPA、Falco、安全）
console-kb	AI 知识库——社区任务和运维手册
kubestellar-mcp	本仓库——适用于 Claude、Cursor、Windsurf、VS Code 的 MCP 服务

kubestellar-mcp 让 AI Agent 通过自然语言检查和操作集群。如需可视化仪表板和 AI 任务，请参阅 KubeStellar Console。

组件

二进制文件	描述
kubestellar-ops	多集群诊断、RBAC 分析、安全检查
kubestellar-deploy	以应用为中心的部署、GitOps、智能工作负载放置

文档

更多文档位于 docs/：

• docs/index.md - 扩展的设置说明、插件工作流、CLI 用法和运维指南
• docs/ARCHITECTURE.md - 两个 MCP 服务的架构概览和贡献者指南、请求生命周期，以及如何添加新工具

如果你要贡献新的 MCP 功能，请从 docs/ARCHITECTURE.md 开始；它最适合帮助你了解服务的组织方式以及应在何处添加新工具。

运维

• docs/slo.md - 服务级别目标和指标
• docs/alerts/ - 与 SLO 对齐、可导入的 Prometheus 告警规则
• docs/dashboards/ - 可导入的 Grafana 仪表板
• runbooks/ - 运维手册（启动/关闭、集群发现失败、凭证轮换、连接中断、发布回滚）
• docs/postmortem-template.md - 事件复盘模板
• docs/severity-levels.md - 事件模板和复盘要求中使用的 P1-P4 事件严重性等级

安装

Homebrew（推荐）

brew tap kubestellar/tap

# Install diagnostics tools
brew install kubestellar-ops

# Install deployment tools
brew install kubestellar-deploy

# Or install both
brew install kubestellar-ops kubestellar-deploy

从发布版本安装

从 GitHub Releases 下载。

从源码安装

前置条件： Go 1.26+（运行 go version 验证）

git clone https://github.com/kubestellar/kubestellar-mcp.git
cd kubestellar-mcp

# Build both binaries
go build -o bin/kubestellar-ops ./cmd/kubestellar-ops
go build -o bin/kubestellar-deploy ./cmd/kubestellar-deploy

sudo mv bin/kubestellar-* /usr/local/bin/

Claude Code 插件

第 1 步：添加 KubeStellar Marketplace

在 Claude Code 中运行：

/plugin marketplace add kubestellar/claude-plugins

第 2 步：安装插件

/plugin install kubestellar-ops
/plugin install kubestellar-deploy

或者：

1. 前往 /plugin → Marketplaces 选项卡 → 点击 kubestellar marketplace 上的 Update
2. 前往 /plugin → Discover 选项卡 → 安装 kubestellar-ops 和/或 kubestellar-deploy

第 3 步：验证

在 Claude Code 中运行 /mcp——你应该会看到：

plugin:kubestellar-ops:kubestellar-ops · ✓ connected
plugin:kubestellar-deploy:kubestellar-deploy · ✓ connected

允许工具免提示运行

添加到 ~/.claude/settings.json：

{
  "permissions": {
    "allow": [
      "mcp__plugin_kubestellar-ops_kubestellar-ops__*",
      "mcp__plugin_kubestellar-deploy_kubestellar-deploy__*"
    ]
  }
}

或者在 Claude Code 中运行：

/allowed-tools add mcp__plugin_kubestellar-ops_kubestellar-ops__*
/allowed-tools add mcp__plugin_kubestellar-deploy_kubestellar-deploy__*

其他 AI 客户端（VS Code、Cursor、Windsurf）

你可以使用 kubestellar-ops --mcp-server 或 kubestellar-deploy --mcp-server，将任一二进制文件作为通用 MCP stdio 服务运行。任何兼容 MCP 的客户端都可以通过 stdio 使用该二进制文件。

VS Code（GitHub Copilot）

创建 .vscode/mcp.json：

{
  "servers": {
    "kubestellar-ops": {
      "command": "kubestellar-ops",
      "args": ["--mcp-server"]
    }
  }
}

Cursor

创建 .cursor/mcp.json：

{
  "mcpServers": {
    "kubestellar-ops": {
      "command": "kubestellar-ops",
      "args": ["--mcp-server"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "kubestellar-ops": {
      "command": "kubestellar-ops",
      "args": ["--mcp-server"]
    }
  }
}

OpenCode

OpenCode 是一款开源 AI 编码 Agent。 将以下内容添加到项目的 opencode.json 或 opencode.jsonc 中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kubestellar-ops": {
      "type": "local",
      "command": ["kubestellar-ops", "--mcp-server"],
      "enabled": true
    },
    "kubestellar-deploy": {
      "type": "local",
      "command": ["kubestellar-deploy", "--mcp-server"],
      "enabled": true
    }
  }
}

添加后，运行 opencode mcp list，并确认两个服务均显示为已连接。

致你的 AI Agent — 将此消息复制并粘贴到 OpenCode 会话中，即可让它自动配置 MCP 工具：

安装 kubestellar-ops 和 kubestellar-deploy：

  # macOS — Homebrew
  brew tap kubestellar/tap
  brew install kubestellar-ops kubestellar-deploy

  # Linux — 从 GitHub Releases 下载
  curl -LO https://github.com/kubestellar/kubestellar-mcp/releases/latest/download/kubestellar-ops_linux_amd64.tar.gz
  curl -LO https://github.com/kubestellar/kubestellar-mcp/releases/latest/download/kubestellar-deploy_linux_amd64.tar.gz
  tar xzf kubestellar-ops_linux_amd64.tar.gz
  tar xzf kubestellar-deploy_linux_amd64.tar.gz
  sudo mv kubestellar-ops kubestellar-deploy /usr/local/bin/

  # 或从源代码构建（适用于任何 OS，需要 Go 1.26+）
  git clone https://github.com/kubestellar/kubestellar-mcp.git
  cd kubestellar-mcp
  go build -o /usr/local/bin/kubestellar-ops ./cmd/kubestellar-ops
  go build -o /usr/local/bin/kubestellar-deploy ./cmd/kubestellar-deploy

然后在项目根目录中创建 opencode.jsonc，内容如下：
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "kubestellar-ops": {
        "type": "local",
        "command": ["kubestellar-ops", "--mcp-server"],
        "enabled": true
      },
      "kubestellar-deploy": {
        "type": "local",
        "command": ["kubestellar-deploy", "--mcp-server"],
        "enabled": true
      }
    }
  }

使用以下命令验证：opencode mcp list

通用 MCP 客户端（stdio）

kubestellar-ops --mcp-server
kubestellar-deploy --mcp-server

Kubernetes RBAC

默认情况下，MCP 二进制文件使用当前激活的 kubeconfig。如果在集群内运行，则将相同权限绑定到 Pod 的 ServiceAccount。

用例	典型权限
kubestellar-ops 只读	对命名空间、节点、Pod、pods/log、服务、端点、部署、ReplicaSet、StatefulSet、DaemonSet、Job、CronJob、事件、resourcequotas、limitranges、Role、RoleBinding、ClusterRole 和 ClusterRoleBinding 执行 get、list、watch
kubestellar-deploy 写入	包含上述全部权限，此外还可对计划管理的资源类型执行 create、update、patch 和 delete

只读 ClusterRole 示例：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: kubestellar-mcp-readonly
rules:
  - apiGroups: [""]
    resources: ["namespaces", "nodes", "pods", "pods/log", "services", "endpoints", "events", "resourcequotas", "limitranges"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps", "batch"]
    resources: ["deployments", "replicasets", "statefulsets", "daemonsets", "jobs", "cronjobs"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["roles", "rolebindings", "clusterroles", "clusterrolebindings"]
    verbs: ["get", "list", "watch"]

对于写入工作流，请在实际需要的资源规则中添加 create、update、patch 和 delete。

故障排除

未显示插件

• 安装或升级二进制文件后，重启 Claude Code、VS Code、Cursor 或 Windsurf。
• 使用 which kubestellar-ops 确认二进制文件位于 PATH 中。
• 如果找不到，请重新安装，或将其移至 PATH 中已有的目录。

权限 / RBAC 错误

• 运行 kubectl auth can-i --list，查看当前身份可访问的内容。
• 将输出与上文 Kubernetes RBAC 部分所述权限进行比较。
• 如有需要，请更新 Role、ClusterRole 或绑定，然后重试 MCP 客户端。

kubeconfig 问题

• 使用 kubectl config current-context 确认当前激活的上下文。
• 检查是否设置了 KUBECONFIG，以及它是否指向预期的 kubeconfig 文件。
• 如果选错了集群，请切换上下文或更新环境变量，然后重试。

手动冒烟测试

• 无需打开 AI 客户端，即可验证 MCP 服务是否能启动。
• 运行以下初始化请求，并确认收到 JSON-RPC 响应。

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | ./bin/kubestellar-ops --mcp-server

更新

通过 Homebrew 更新 CLI 工具：

brew update
brew upgrade kubestellar-ops kubestellar-deploy

在 Claude Code 中更新插件：

/plugin update kubestellar-ops
/plugin update kubestellar-deploy

---

kubestellar-ops

多集群 Kubernetes 诊断、RBAC 分析和安全检查。

使用示例

• “列出我的 Kubernetes 集群”
• “查找所有集群中存在问题的 Pod”
• “检查安全配置错误”
• “管理员服务账户拥有哪些权限？”
• “显示 kube-system 中的警告事件”

功能

类别	工具
集群	list_clusters、get_cluster_health、get_nodes、audit_kubeconfig
工作负载	get_pods、get_deployments、get_services、get_events、describe_pod、get_pod_logs
RBAC	get_roles、get_cluster_roles、get_role_bindings、can_i、analyze_subject_permissions
诊断	find_pod_issues、find_deployment_issues、check_resource_limits、check_security_issues
Gatekeeper	check_gatekeeper、install_ownership_policy、list_ownership_violations
升级	detect_cluster_type、get_cluster_version_info、check_helm_release_upgrades
GitOps	detect_drift

斜杠命令

命令	说明
/k8s-health	检查所有集群的健康状况
/k8s-issues	查找 Pod 和部署问题
/k8s-security	检查安全配置错误
/k8s-rbac	分析 RBAC 权限
/k8s-analyze	全面分析命名空间
/k8s-audit-kubeconfig	审计 kubeconfig 集群并建议清理
/k8s-ownership	使用 OPA Gatekeeper 管理所有权跟踪
/k8s-upgrade-check	检查可用升级
/k8s-upgrade	升级集群（主节点和节点）

---

kubestellar-deploy

以应用为中心的多集群部署和运维。

使用示例

• “nginx 在哪里运行？”
• “获取我的 api 服务的日志”
• “将我的 ML 模型部署到配备 GPU 的集群”
• “我的集群与 git 保持同步了吗？”
• “将我的应用扩展到所有集群中的 5 个副本”

功能

类别	工具
应用发现	get_app_instances、get_app_status、get_app_logs
部署	deploy_app、scale_app、patch_app
放置	list_cluster_capabilities、find_clusters_for_workload
GitOps	sync_from_git、detect_drift、reconcile、preview_changes
Helm	helm_install、helm_uninstall、helm_list、helm_rollback
Kustomize	kustomize_build、kustomize_apply、kustomize_delete
资源	kubectl_apply、delete_resource
标签	add_labels、remove_labels

斜杠命令

命令	说明
/app-status	显示应用在所有集群中的状态
/app-logs	获取应用的聚合日志
/deploy	部署或更新应用
/gitops-sync	从 git 同步集群
/gitops-drift	检查与 git 的偏差

工作流示例

“我的应用在哪里运行？”

nginx is running on 3 clusters:
  - prod-east: 3 replicas, healthy
  - prod-west: 3 replicas, healthy
  - staging: 1 replica, healthy

“部署到 GPU 集群”

Found 2 clusters with nvidia.com/gpu
Deployed to gpu-cluster-1, gpu-cluster-2
All healthy

“检查偏差”

Drift detected:
  - prod-west: ConfigMap/app-config differs
  - staging: Deployment/api has extra replicas

“使用 Helm 安装 nginx-ingress”

Installing nginx-ingress to 3 clusters...
  - prod-east: Installed nginx-ingress v1.10.0
  - prod-west: Installed nginx-ingress v1.10.0
  - staging: Installed nginx-ingress v1.10.0
All releases healthy

“应用 kustomize 覆盖层”

Building kustomize from overlays/production...
Applied to 2 clusters:
  - prod-east: 5 resources applied
  - prod-west: 5 resources applied

“删除测试部署”

Deleted deployment/test from 3 clusters:
  - prod-east: deleted
  - prod-west: deleted
  - staging: deleted

---

CLI 用法

kubestellar-ops

# Run as MCP server (for Claude Code)
kubestellar-ops --mcp-server

# List clusters
kubestellar-ops clusters list

# Check cluster health
kubestellar-ops clusters health

kubestellar-deploy

# Run as MCP server (deployment, GitOps, Helm, kubectl, and kustomize tools)
kubestellar-deploy --mcp-server

# Show version information
kubestellar-deploy version

# Generate shell completion
kubestellar-deploy completion bash

kubestellar-deploy 当前不提供独立的部署子命令。在 MCP 服务模式之外，CLI 仅提供 version、completion 和 help 等信息类命令。应用部署、GitOps、Helm、kubectl、kustomize 和标签工作流可通过使用 --mcp-server 启动的 MCP 工具服务使用。若要指定其他 Kubernetes 环境，请在启动二进制文件前，将 KUBECONFIG 指向所需的 kubeconfig（或在该 kubeconfig 中切换活动上下文）。

环境变量

变量	使用方	描述
KUBECONFIG	kubestellar-ops、kubestellar-deploy	要使用的 kubeconfig 文件路径，替代 Kubernetes 客户端默认的查找路径
ANTHROPIC_API_KEY	kubestellar-ops	query 命令以及由 Claude 支持的自然语言集群查询所必需

相关运行时标志

kubestellar-ops 还继承了 kubectl 的 Kubernetes 客户端标准标志，因此贡献者可以在运行时覆盖集群选择和请求行为，无需额外的环境变量。常见示例包括：

• --context 用于选择 kubeconfig 上下文
• --namespace 用于限定命名空间范围内的操作
• --request-timeout 用于覆盖 API 请求超时时间
• --cluster、--user、--server、--token 和 TLS 标志，用于高级身份验证／连接覆盖
• --all-clusters、--target-cluster 和 --mcp-server 用于 KubeStellar 特定行为

kubestellar-deploy 目前提供 --mcp-server 作为运行时标志，除 Kubernetes 客户端配置外，无需任何额外的环境变量。

相关项目

• KubeStellar - 多集群编排平台
• KubeStellar Console - 用于多集群管理的 AI 驱动型 Web 仪表板

贡献

欢迎贡献！请阅读我们的贡献指南。

许可证

Apache License 2.0 - 详情请参阅 LICENSE。