Kubectl MCP 工具

一个用于 Kubernetes 的模型上下文协议 (MCP) 服务器，使 Claude、Cursor 等 AI 助手能够通过自然语言与 Kubernetes 集群交互。

⚠️ 已知问题

我们目前在服务器上遇到 JSON 解析问题。这导致 MCP 在以下环境中运行出现困难：

• Claude
• Cursor
• Windsurf

我正在积极解决这些问题。由于我独立处理故障排除过程，因此解决可能需要一些时间，因为我正在为每个服务单独进行详细测试。如果您可以调试这些问题，请随时提交 Pull Request。

非常感谢您的耐心和持续支持。🙏

感谢您的理解！

功能特性

核心 Kubernetes 操作

• [x] 连接到 Kubernetes 集群
• [x] 列出和管理 Pod、Service、Deployment 和 Node
• [x] 创建、删除和描述 Pod 和其他资源
• [x] 获取 Pod 日志和 Kubernetes 事件
• [x] 支持 Helm v3 操作（安装、升级、卸载）
• [x] 支持 kubectl explain 和 api-resources
• [x] 为后续命令选择命名空间（内存持久化）
• [x] 端口转发到 Pod
• [x] 伸缩 Deployment 和 StatefulSet
• [x] 在容器中执行命令
• [x] 管理 ConfigMap 和 Secret
• [x] 将 Deployment 回滚到以前的版本
• [x] Ingress 和 NetworkPolicy 管理
• [x] 在集群之间切换上下文

自然语言处理

• [x] 处理 kubectl 操作的自然语言查询
• [x] 具有先前操作记忆的上下文感知命令
• [x] Kubernetes 概念的人性化解释
• [x] 从意图智能构建命令
• [x] 在专用工具不可用时回退到 kubectl
• [x] 支持离线/测试场景的模拟数据
• [x] 命名空间感知查询处理

监控

• [x] 集群健康监控
• [x] 资源利用率跟踪
• [x] Pod 状态和健康检查
• [x] 事件监控和警报
• [x] 节点容量和分配分析
• [x] 历史性能跟踪
• [x] 通过 kubectl top 获取资源使用统计信息
• [x] 容器就绪性和活跃性跟踪

安全

• [x] RBAC 验证和核查
• [x] 安全上下文审计
• [x] 与 Kubernetes API 的安全连接
• [x] 凭证管理
• [x] 网络策略评估
• [x] 容器安全扫描
• [x] 安全最佳实践执行
• [x] Role 和 ClusterRole 管理
• [x] ServiceAccount 创建和绑定
• [x] PodSecurityPolicy 分析
• [x] RBAC 权限审计
• [x] 安全上下文验证

诊断

• [x] 集群诊断和故障排除
• [x] 配置验证
• [x] 错误分析和恢复建议
• [x] 连接状态监控
• [x] 日志分析和模式检测
• [x] 资源约束识别
• [x] Pod 健康检查诊断
• [x] 常见错误模式识别
• [x] 资源验证以查找错误配置
• [x] 详细的活跃性和就绪性探针验证

高级功能

• [x] 支持多种传输协议（stdio、SSE）
• [x] 与多个 AI 助手集成
• [x] 可扩展的工具框架
• [x] 自定义资源定义支持
• [x] 跨命名空间操作
• [x] 对多个资源进行批量操作
• [x] 智能资源关系映射
• [x] 带有恢复建议的错误解释
• [x] 卷管理和识别

架构

模型上下文协议 (MCP) 集成

Kubectl MCP 工具实现了 模型上下文协议 (MCP)，使 AI 助手能够通过标准化接口与 Kubernetes 集群交互。该架构包括：

1. MCP 服务器：一个兼容的服务器，用于处理来自 MCP 客户端（AI 助手）的请求
2. 工具注册表：将 Kubernetes 操作注册为带有模式的 MCP 工具
3. 传输层：支持 stdio、SSE 和 HTTP 传输方法
4. 核心操作：将工具调用转换为 Kubernetes API 操作
5. 响应格式化程序：将 Kubernetes 响应转换为符合 MCP 的响应

请求流程

双模式操作

该工具以两种模式运行：

1. CLI 模式：用于执行 Kubernetes 操作的直接命令行界面
2. 服务器模式：作为 MCP 服务器运行，以处理来自 AI 助手的请求

安装

有关详细的安装说明，请参阅 安装指南。

您可以直接从 PyPI 安装 kubectl-mcp-tool：

pip install kubectl-mcp-tool

对于特定版本：

pip install kubectl-mcp-tool==1.1.0

该软件包可在 PyPI 上找到：https://pypi.org/project/kubectl-mcp-tool/1.1.0/

前提条件

• Python 3.9+
• 已安装并配置 kubectl CLI
• 访问 Kubernetes 集群
• pip（Python 包管理器）

全局安装

# 从 PyPI 安装最新版本
pip install kubectl-mcp-tool

# 或者从 GitHub 安装开发版本
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git

本地开发安装

# 克隆存储库
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

# 以开发模式安装
pip install -e .

验证安装

安装后，验证该工具是否正常工作：

# 检查 CLI 模式
kubectl-mcp --help

注意：此工具旨在用作 AI 助手连接到的 MCP 服务器，而不是直接替代 kubectl。可用的主要命令是 kubectl-mcp serve，它启动 MCP 服务器。

与 AI 助手一起使用

Claude Desktop

将以下内容添加到您的 Claude Desktop 配置中，位于 ~/.config/claude/mcp.json（Windows：%APPDATA%\Claude\mcp.json）：

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.minimal_wrapper"],
      "env": {
        "KUBECONFIG": "/path/to/your/.kube/config"
      }
    }
  }
}

Cursor AI

通过添加新的全局 MCP 服务器，将以下内容添加到 Cursor AI 设置中的 MCP 下：

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.minimal_wrapper"],
      "env": {
        "KUBECONFIG": "/path/to/your/.kube/config",
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin"
      }
    }
  }
}

将此配置保存到 ~/.cursor/mcp.json 以进行全局设置。

注意：将 /path/to/your/.kube/config 替换为您的 kubeconfig 文件的实际路径。在大多数系统上，这是 ~/.kube/config。

Windsurf

将以下内容添加到您的 Windsurf 配置中，位于 ~/.config/windsurf/mcp.json（Windows：%APPDATA%\WindSurf\mcp.json）：

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.minimal_wrapper"],
      "env": {
        "KUBECONFIG": "/path/to/your/.kube/config"
      }
    }
  }
}

自动配置

要自动配置所有受支持的 AI 助手，请运行提供的安装脚本：

bash install.sh

此脚本将：

1. 安装所需的依赖项
2. 为 Claude、Cursor 和 WindSurf 创建配置文件
3. 设置正确的路径和环境变量
4. 测试您的 Kubernetes 连接

前提条件

1. 已安装 kubectl 并在您的 PATH 中
2. 有效的 kubeconfig 文件
3. 访问 Kubernetes 集群
4. Helm v3（可选，用于 Helm 操作）

示例

列出 Pod

列出默认命名空间中的所有 Pod

部署应用程序

使用 nginx:latest 镜像创建一个名为 nginx-test 的 Deployment，包含 3 个副本

检查 Pod 日志

获取 nginx-test Pod 的日志

端口转发

将本地端口 8080 转发到 nginx-test Pod 上的端口 80

开发

# 克隆存储库
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

# 安装依赖项
pip install -r requirements.txt

# 以开发模式安装
pip install -e .

# 运行测试
python -m python_tests.test_all_features

项目结构

├── kubectl_mcp_tool/         # 主包
│   ├── __init__.py           # 包初始化
│   ├── cli.py                # CLI 入口点
│   ├── mcp_server.py         # MCP 服务器实现
│   ├── mcp_kubectl_tool.py   # 主要 kubectl MCP 工具实现
│   ├── natural_language.py   # 自然语言处理
│   ├── diagnostics.py        # 诊断功能
│   ├── core/                 # 核心功能
│   ├── security/             # 安全操作
│   ├── monitoring/           # 监控功能
│   ├── utils/                # 实用函数
│   └── cli/                  # CLI 功能组件
├── python_tests/             # 测试套件
│   ├── run_mcp_tests.py      # 测试运行器脚本
│   ├── mcp_client_simulator.py # 用于模拟测试的 MCP 客户端模拟器
│   ├── test_utils.py         # 测试实用程序
│   ├── test_mcp_core.py      # 核心 MCP 测试
│   ├── test_mcp_security.py  # 安全测试
│   ├── test_mcp_monitoring.py # 监控测试
│   ├── test_mcp_nlp.py       # 自然语言测试
│   ├── test_mcp_diagnostics.py # 诊断测试
│   └── mcp_test_strategy.md  # 测试策略文档
├── docs/                     # 文档
│   ├── README.md             # 文档概述
│   ├── INSTALLATION.md       # 安装指南
│   ├── integration_guide.md  # 集成指南
│   ├── cursor/               # Cursor 集成文档
│   ├── windsurf/             # Windsurf 集成文档
│   └── claude/               # Claude 集成文档
├── compatible_servers/       # 兼容的 MCP 服务器实现
│   ├── cursor/               # Cursor 兼容服务器
│   ├── windsurf/             # Windsurf 兼容服务器
│   ├── minimal/              # 最小服务器实现
│   └── generic/              # 通用 MCP 服务器
├── requirements.txt          # Python 依赖项
├── setup.py                  # 包设置脚本
├── pyproject.toml            # 项目配置
├── MANIFEST.in               # 包清单
├── LICENSE                   # MIT 许可证
├── CHANGELOG.md              # 版本历史
├── .gitignore                # Git 忽略文件
├── install.sh                # 安装脚本
├── publish.sh                # PyPI 发布脚本
└── start_mcp_server.sh       # 服务器启动脚本

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 存储库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。