MCP Kubernetes Go

MCP Kubernetes 故障排除服务器

一个用于Kubernetes集群故障排除和检查的模型上下文协议（MCP）服务器，采用Go语言实现。该服务器为调试和监控目的提供对Kubernetes资源的只读访问权限。

特点/特性

✅ 只读操作安全、无损的故障排除\ ✅ 全面的资源覆盖Pod、部署（Deployments）、服务（Services）、入口（Ingresses）、配置映射（ConfigMaps）、密钥（Secrets）、事件（Events）、节点（Nodes）、命名空间（Namespaces）\ ✅（对号，表示正确、同意或确认） 详细资源检查获取任何 Kubernetes 资源的详细信息\ ✅ 日志访问获取容器日志，支持可配置的尾随（实时）查看\ ✅ 事件监控查看集群事件，并具备过滤功能\ ✅ 节点状态监控集群节点的健康状况和资源使用情况\ ✅ 命名空间管理列出并检查命名空间\ ✅ Stdio 传输与Cursor、Claude Desktop和其他MCP客户端兼容

快速入门

1. 先决条件

• Go 1.23.0 或更高版本
• 访问 Kubernetes 集群
• 有效的 kubeconfig 文件或集群内配置

2. 构建并运行

go mod tidy
go build -o mcp-kubernetes-server.exe .
./mcp-kubernetes-server.exe

3. 配置

服务器自动检测Kubernetes配置：

• “在集群内”或“集群内部”在Pod内运行时使用服务账户
• “Out-of-cluster”可以翻译为“集群外”或“非集群内”。这个术语通常用于描述不在某个特定集群或系统范围内的元素、数据或服务用途 ~/.kube/config 或者 KUBECONFIG 环境变量

MCP客户端配置

Cursor / VS Code（可直接作为中文表述，因为“Cursor”和“VS Code”在中文中通常也直接使用原名，无需翻译）

创造 .cursor/mcp.json 或者 .vscode/mcp.json：

{
  "mcpServers": {
    "kubernetes-troubleshooting": {
      "command": "C:\\Users\\PC\\Desktop\\mcp-kubernetes-troubleshooting\\mcp-kubernetes-server.exe",
      "env": {
        "KUBECONFIG": "C:\\Users\\PC\\.kube\\config"
      }
    }
  }
}

Claude Desktop（可译为“Claude桌面版”）

添加到Claude桌面配置文件中：

macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json\ Windows： %APPDATA%\\Claude\\claude_desktop_config.json\ Linux（发音类似“林克斯”）： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kubernetes-troubleshooting": {
      "command": "/path/to/mcp-kubernetes-server",
      "env": {
        "KUBECONFIG": "/path/to/kubeconfig"
      }
    }
  }
}

可用工具（共30个）

Pod 工具（3 个工具）

1. get_pods - 列出Pods

列出命名空间中的所有 Pod，并显示其状态、就绪状态以及重启次数。

输入：

{
  "namespace": "default"
}

输出：

Pods in namespace 'default':

| Name | Status | Ready | Restarts | Age |
|------|--------|-------|----------|-----|
| my-pod | Running | 1/1 | 0 | 2h |

2. get_pod_details - 获取Pod详情

获取特定Pod的详细信息，包括事件、状态和容器状态。

输入：

{
  "name": "my-pod",
  "namespace": "default"
}

3. get_pod_logs - 获取Pod日志

从具有可配置尾随功能的Pod容器中获取日志。

输入：

{
  "name": "my-pod",
  "namespace": "default",
  "container": "main-container",
  "tail_lines": 100
}

部署工具（2个工具）

4. get_deployments - 列出部署

列出命名空间中的部署及其状态和副本数量。

输入：

{
  "namespace": "default"
}

5. get_deployment_details - 获取部署详情

获取有关部署的详细信息，包括发布状态和条件。

输入：

{
  "name": "my-deployment",
  "namespace": "default"
}

服务工具（4件工具）

6. get_services - 列出服务

列出命名空间中的服务，包括其类型、集群IP和端口。

输入：

{
  "namespace": "default"
}

7. get_service_details - 获取服务详情

获取服务的详细信息，包括端点和选择器。

输入：

{
  "name": "my-service",
  "namespace": "default"
}

8. get_ingresses - 列出入口（Ingresses）

列出命名空间中的入口（Ingress），并显示其主机和状态。

输入：

{
  "namespace": "default"
}

9. get_ingress_details - 获取入境详情

获取关于入口的详细信息，包括规则和后端服务。

输入：

{
  "name": "my-ingress",
  "namespace": "default"
}

资源工具（6种工具）

10. get_configmaps - 列出 ConfigMaps

列出命名空间中的 ConfigMaps。

输入：

{
  "namespace": "default"
}

11. get_secrets - 列出秘密

列出命名空间中的秘密（仅元数据，不包含敏感数据）。

输入：

{
  "namespace": "default"
}

12. get_events - 获取事件

获取命名空间中的事件，可选择按资源类型和名称进行过滤。

输入：

{
  "namespace": "default",
  "resource_type": "Pod",
  "resource_name": "my-pod"
}

13. get_node_status - 获取节点状态

获取集群节点状态和资源使用情况。

输入：

{}

14. get_namespaces - 获取命名空间

列出集群中的所有命名空间。

输入：

{}

15. describe_resource - 描述资源

获取任何 Kubernetes 资源的详细描述（类似于 kubectl describe）。

输入：

{
  "resource_type": "pod",
  "name": "my-pod",
  "namespace": "default"
}

体积工具（4种工具）

16. get_persistent_volumes - 列出持久卷

列出持久卷及其状态、容量和访问模式。

输入：

{}

17. get_persistent_volume_claims - 列出PVC（个人虚拟卷/持久卷声明）

列出命名空间中的持久卷声明。

输入：

{
  "namespace": "default"
}

18. get_persistent_volume_details - 获取PV详情

获取特定持久卷的详细信息。

输入：

{
  "name": "my-pv"
}

19. get_storage_classes - 列出存储类别

列出集群中可用的存储类别。

输入：

{}

健康检查工具（4种工具）

20. get_pod_health_status - 获取Pod健康状态

获取命名空间中所有Pod的健康检查状态。

输入：

{
  "namespace": "default"
}

21. get_health_check_details - 获取健康检查详情

获取特定Pod的详细健康检查信息。

输入：

{
  "name": "my-pod",
  "namespace": "default"
}

22. get_node_health_status - 获取节点健康状态

获取集群中所有节点的健康状态。

输入：

{}

23. get_cluster_health_summary - 获取集群健康状况摘要

获取集群整体健康状态的概要。

输入：

{}

度量工具（5种工具）

24. get_node_resource_usage - 获取节点资源使用情况

获取所有节点的CPU和内存使用情况（需要metrics-server）。

输入：

{}

25. get_pod_resource_usage - 获取Pod资源使用情况

获取命名空间中所有Pod的CPU和内存使用情况（需要metrics-server）。

输入：

{
  "namespace": "default"
}

26. get_pod_resource_details - 获取Pod资源详情

获取特定Pod的详细资源使用情况（需要metrics-server）。

输入：

{
  "name": "my-pod",
  "namespace": "default"
}

27. get_node_disk_usage - 获取节点磁盘使用情况

获取所有节点的磁盘使用情况信息。

输入：

{}

28. get_resource_quotas - 获取资源配额

列出命名空间中的资源配额。

输入：

{
  "namespace": "default"
}

网络工具（5种工具）

29. get_network_policies - 列出网络策略

列出命名空间中的网络策略。

输入：

{
  "namespace": "default"
}

30. get_network_policy_details - 获取网络策略详情

获取特定网络策略的详细信息。

输入：

{
  "name": "my-network-policy",
  "namespace": "default"
}

31. get_endpoints - 列出终端节点

列出命名空间中的端点。

输入：

{
  "namespace": "default"
}

32. get_endpoint_details - 获取终端详细信息

获取特定终端节点的详细信息。

输入：

{
  "name": "my-service",
  "namespace": "default"
}

33. get_network_policy_summary - 获取网络策略摘要

获取所有命名空间中所有网络策略的摘要。

输入：

{}

安全特性

✅ 只读访问所有操作均为只读，不允许修改\ ✅ RBAC合规性尊重 Kubernetes 的基于角色的访问控制（RBAC）权限\ ✅ 命名空间隔离可以配置以访问特定的命名空间\ ✅ 无敏感数据秘密被列出，但内容未被公开\ ✅ 事件过滤事件可以根据资源类型和名称进行过滤\ ✅ 安全日志访问容器日志在限制条件下安全获取

故障排除示例

示例1：调试失败的Pod

{
  "tool": "get_pod_details",
  "input": {
    "name": "failing-pod",
    "namespace": "production"
  }
}

示例2：检查部署状态

{
  "tool": "get_deployment_details",
  "input": {
    "name": "web-app",
    "namespace": "production"
  }
}

示例3：获取最近事件

{
  "tool": "get_events",
  "input": {
    "namespace": "production",
    "resource_type": "Pod"
  }
}

示例4：检查节点健康状况

{
  "tool": "get_node_status",
  "input": {}
}

示例5：获取应用程序日志

{
  "tool": "get_pod_logs",
  "input": {
    "name": "web-app-7d4b8c9f6-abc12",
    "namespace": "production",
    "container": "web",
    "tail_lines": 200
  }
}

发展

项目结构

mcp-kubernetes-troubleshooting/
├── main.go              # Server setup and tool registration
├── types.go             # Input/output type definitions
├── k8s_client.go        # Kubernetes client initialization
├── pod_tools.go         # Pod-related tools
├── deployment_tools.go  # Deployment-related tools
├── service_tools.go     # Service and Ingress tools
├── resource_tools.go    # ConfigMaps, Secrets, Events, Nodes, Namespaces
├── volume_tools.go      # Persistent Volumes, PVCs, Storage Classes
├── health_tools.go      # Health check status tools
├── metrics_tools.go     # Resource utilization metrics
├── network_tools.go     # Network policies and endpoints
├── go.mod               # Go dependencies
├── go.sum               # Dependency checksums
├── README.md            # This file

建筑

# Build for current platform
go build -o mcp-kubernetes-server .

# Build for Linux
GOOS=linux GOARCH=amd64 go build -o mcp-kubernetes-server-linux .

# Build for macOS
GOOS=darwin GOARCH=amd64 go build -o mcp-kubernetes-server-macos .

# Build for Windows
GOOS=windows GOARCH=amd64 go build -o mcp-kubernetes-server.exe .

测试

# Test with local kubeconfig
KUBECONFIG=~/.kube/config ./mcp-kubernetes-server

# Test with specific namespace
KUBECTL_NAMESPACE=production ./mcp-kubernetes-server

要求

• Go 1.23.0 或更高版本
• Kubernetes 集群访问
• MCP Go SDK 版本 1.0.0
• Kubernetes Go 客户端 v0.34.1
• Kubernetes指标API v0.34.1 （用于资源使用工具）

依赖项

• github.com/modelcontextprotocol/go-sdk - MCP协议实现
• k8s.io/api Kubernetes API 类型
• k8s.io/apimachinery Kubernetes API 机制
• k8s.io/client-go - Kubernetes Go 客户端
• k8s.io/metrics Kubernetes指标API客户端

用例

• 生产调试安全检查生产集群，无风险
• 持续集成/持续交付（CI/CD）监控检查部署状态和健康状况
• 事件响应在停电期间快速收集信息
• 开发支持调试本地和开发环境
• 集群健康监测监控节点状态和资源使用情况
• 日志分析访问容器日志以进行调试
• 事件调查审查集群事件以进行故障排除

未来改进/增强

可能的补充：

• \[ \] 自定义资源定义支持
• \[ \] 支持多集群
• \[ \] 资源比较工具
• \[ \] 性能指标
• \[ \] 警报集成
• \[ \] 资源依赖映射
• \[ \] 备份和恢复状态
• \[ \] 安全策略检查
• \[ \] 成本分析工具
• \[ \] 自动化故障排除建议

许可证

麻省理工学院（MIT）

参考文献

• 模型上下文协议
• MCP Go SDK（注：MCP可能代表某个特定的服务或平台，但在此上下文中未给出具体含义，因此直接保留原样；SDK即软件开发工具包）
• Kubernetes Go 客户端
• Kubernetes API 文档