mcp-kubernetes

mcp-kubernetes

mcp-kubernetes 是一个模型上下文协议（MCP）服务，可让 AI 助手与 Kubernetes 集群交互。它充当 AI 工具（如 Claude、Cursor 和 GitHub Copilot）与 Kubernetes 之间的桥梁，将自然语言请求转换为 Kubernetes 操作，并以 AI 工具能够理解的格式返回结果。

它可让 AI 工具：

• 查询 Kubernetes 资源
• 执行 kubectl 命令
• 通过自然语言交互管理 Kubernetes 集群
• 诊断和解读 Kubernetes 资源的状态

工作原理

安装方法

不再提供或支持容器镜像。请在本地安装已发布的二进制文件，并配置 MCP 客户端通过 stdio 子进程运行它。

本地安装

# For Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# For MacOS
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

在 Claude Desktop、Cursor、ChatGPT Copilot、Github Copilot 和其他受支持的 AI 客户端中配置 MCP 服务，例如：

{
  "mcpServers": {
    "kubernetes": {
      "command": "<path of binary 'mcp-kubernetes'>",
      "args": ["--transport", "stdio"],
      "env": {
        "KUBECONFIG": "<your-kubeconfig-path>"
      }
    }
  }
}

选项

环境变量：

• KUBECONFIG：kubeconfig 文件的路径，例如 /home/<username>/.kube/config。
• USE_LEGACY_TOOLS：设为 true 可使用多个专用 kubectl 工具，而不是统一的 call_kubectl 工具（默认值：false）。

命令行参数：

Usage of ./mcp-kubernetes:
      --access-level string       Access level (readonly, readwrite, or admin) (default "readonly")
      --additional-tools string   Comma-separated list of additional tools to support (kubectl is always enabled). Available: helm,cilium,hubble
      --allow-namespaces string   Comma-separated list of namespaces to allow (empty means all allowed)
      --otlp-endpoint string      OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317, default "")
      --timeout int               Timeout for command execution in seconds, default is 60s (default 60)
      --transport string          Transport mechanism to use (stdio only) (default "stdio")

统一工具与旧版工具

默认情况下，mcp-kubernetes 使用单个统一的 call_kubectl 工具，将所有 kubectl 操作整合到一个工具接口中。在保持完整功能的同时，这能显著减少上下文消耗。

如需使用包含多个专用工具（6-7 个独立工具）的旧版模式，请设置环境变量：

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "env": {
        "USE_LEGACY_TOOLS": "true"
      }
    }
  }
}

访问级别

--access-level 标志用于控制允许执行的操作：

• readonly（默认）：仅允许读取操作（get、describe、logs 等）。
• readwrite：允许读取和写入操作（create、delete、apply 等）。
• admin：允许执行所有操作，包括管理员操作（cordon、drain、taint 等）。

工具和操作会在注册时根据访问级别进行筛选，因此 AI 助手只能看到自己实际能够使用的操作。

配置示例：

// Read-only access (default)
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes"
    }
  }
}

// Read-write access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "readwrite"]
    }
  }
}

// Admin access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "admin"]
    }
  }
}

用法

在 AI 客户端中询问任何有关 Kubernetes 集群的问题。MCP 工具可帮助 AI 助手更轻松地理解和使用 kubectl 操作。

查询示例

What is the status of my Kubernetes cluster?

What is wrong with my nginx pod?

Show me all deployments in the production namespace

Scale my web deployment to 5 replicas

Check if I have permission to create pods

What is my current kubectl context?

List all available kubectl contexts

Switch to the production context

可用工具

统一工具（默认）

默认情况下，mcp-kubernetes 使用单个统一的 call_kubectl 工具处理所有 kubectl 操作。与旧版多工具方案相比，这种方式能显著减少上下文消耗。

call_kubectl - 执行 kubectl 命令

• 适用于：所有访问级别（操作会根据访问级别进行筛选）
• 参数：
  • command：要执行的完整 kubectl 命令，包含 'kubectl' 前缀（例如，“kubectl get pods -n default”、“kubectl apply -f deployment.yaml”）
• 示例：

  # Get pods
  command: "kubectl get pods -n default"
  
  # Apply configuration
  command: "kubectl apply -f deployment.yaml"
  
  # Scale deployment
  command: "kubectl scale deployment nginx --replicas=3"
  

旧版工具（可选）

当 USE_LEGACY_TOOLS=true 时，mcp-kubernetes 服务会提供多个专用 kubectl 工具，将相关操作归为一组。工具会根据你的访问级别自动筛选。

Kubectl 工具

# Get all pods
operation: "get"
resource: "pods"
args: "--all-namespaces"

# Apply a configuration
operation: "apply"
resource: ""
args: "-f deployment.yaml"

# Drain a node (admin only)
operation: "drain"
resource: "node"
args: "worker-1 --ignore-daemonsets"

# Add a taint (admin only)
operation: "taint"
resource: "nodes"
args: "worker-1 key=value:NoSchedule"

# Scale a deployment
operation: "scale"
resource: "deployment"
args: "nginx --replicas=3"

# Check rollout status
operation: "rollout"
resource: "status"
args: "deployment/nginx"

# Add a label
operation: "label"
resource: "pods"
args: "nginx-pod app=web"

# Set image
operation: "set"
resource: "image"
args: "deployment/nginx nginx=nginx:latest"

# View logs
operation: "logs"
resource: ""
args: "nginx-pod -f"

# Execute command in pod
operation: "exec"
resource: ""
args: "nginx-pod -- ls /app"

# Get cluster info
operation: "cluster-info"
resource: ""
args: ""

# Explain pod spec
operation: "explain"
resource: "pod.spec"
args: "--recursive"

# Check permissions
operation: "auth"
resource: "can-i"
args: "create pods"

# Approve certificate
operation: "certificate"
resource: "approve"
args: "csr-name"

# Get current context
operation: "config"
resource: "current-context"
args: ""

# List all contexts
operation: "config"
resource: "get-contexts"
args: ""

# Switch context (readwrite/admin only)
operation: "config"
resource: "use-context"
args: "my-cluster-context"

command: "list --all-namespaces"

command: "status"

command: "status"
command: "observe observe --namespace backend-jobs  --from-label 'app=web'"
command: "list nodes"

遥测

默认启用遥测收集。

如需退出，请将环境变量 KUBERNETES_MCP_COLLECT_TELEMETRY=false 设为相应值。

OpenTelemetry 支持

mcp-kubernetes 服务支持使用 OpenTelemetry Protocol (OTLP) 导出遥测数据。你可以配置 OTLP 端点，将跟踪数据发送到任何兼容 OpenTelemetry 的后端：

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--otlp-endpoint", "localhost:4317"]
    }
  }
}

开发

如何检查 MCP 服务的请求和响应：

npx @modelcontextprotocol/inspector <path of binary 'mcp-kubernetes'>

贡献

本项目欢迎贡献和建议。大多数贡献都要求你同意贡献者许可协议（CLA），声明你有权授予我们使用你的贡献的权利，并且确实授予了这些权利。详情请访问 https://cla.opensource.microsoft.com。

提交拉取请求时，CLA 机器人会自动判断你是否需要提供 CLA，并相应地为 PR 添加标记（例如，状态检查、评论）。只需按照机器人提供的说明操作即可。对于所有使用我们 CLA 的代码仓库，你只需完成一次此操作。

本项目已采用 Microsoft 开源行为准则。如需了解更多信息，请参阅行为准则常见问题，或发送邮件至 [email protected] 联系我们，提出其他问题或意见。

商标

本项目可能包含其他项目、产品或服务的商标或徽标。经授权使用 Microsoft 商标或徽标时，须遵守并遵循 Microsoft 商标与品牌指南。在本项目的修改版本中使用 Microsoft 商标或徽标，不得造成混淆或暗示 Microsoft 提供赞助。使用第三方商标或徽标时，须遵守相应第三方的政策。