Kubectl MCP 工具
Kubernetes 的模型上下文协议 (MCP) 服务器，使 Claude、Cursor 等 AI 助手能够通过自然语言与 Kubernetes 集群进行交互。
特征
核心 Kubernetes 操作
- [x] 连接到 Kubernetes 集群
- [x] 列出和管理 Pod、服务、部署和节点
- [x] 创建、删除和描述 Pod 和其他资源
- [x] 获取 pod 日志和 Kubernetes 事件
- [x] 支持 Helm v3 操作（安装、升级、卸载）
- [x] kubectl explain 和 api-resources 支持
- [x] 为下一个命令选择命名空间（内存持久性）
- [x] 端口转发至 Pod
- [x] 扩展部署和状态集
- [x] 在容器中执行命令
- [x] 管理 ConfigMap 和 Secrets
- [x] 回滚部署到以前的版本
- [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] 角色和 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 集群交互。该架构包括：
- MCP 服务器：兼容 MCP 客户端（AI 助手）请求的服务器
- 工具注册表：将 Kubernetes 操作注册为具有模式的 MCP 工具
- 传输层：支持 stdio、SSE 和 HTTP 传输方法
- 核心操作：将工具调用转换为 Kubernetes API 操作
- 响应格式化程序：将 Kubernetes 响应转换为符合 MCP 的响应
请求流程
双模式操作
该工具有两种运行模式：
- CLI 模式：直接命令行界面执行 Kubernetes 操作
- 服务器模式：作为 MCP 服务器运行，处理来自 AI 助手的请求
安装
有关详细安装说明，请参阅安装指南。
您可以直接从 PyPI 安装 kubectl-mcp-tool：
pip install kubectl-mcp-tool
对于特定版本：
pip install kubectl-mcp-tool==1.1.1
该软件包可在 PyPI 上获得： https://pypi.org/project/kubectl-mcp-tool/1.1.1/
先决条件
- Python 3.9+
- 安装并配置 kubectl CLI
- 访问 Kubernetes 集群
- pip（Python 包管理器）
全局安装
# Install latest version from PyPI
pip install kubectl-mcp-tool
# Or install development version from GitHub
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git
本地开发安装
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server
# Install in development mode
pip install -e .
验证安装
安装后，验证该工具是否正常工作：
# Check CLI mode
kubectl-mcp --help
注意：此工具旨在用作 AI 助手连接的 MCP 服务器，而非直接替代 kubectl。主要可用的命令是kubectl-mcp serve ，用于启动 MCP 服务器。
与人工智能助手一起使用
使用 MCP 服务器
MCP 服务器 ( kubectl_mcp_tool.mcp_server ) 是基于 FastMCP SDK 构建的强大实现，可增强不同 AI 助手之间的兼容性：
注意：如果您在 MCP Server 实现中遇到任何错误，可以通过将配置中的kubectl_mcp_tool.mcp_server替换为kubectl_mcp_tool.minimal_wrapper来回退到使用最小包装器。最小包装器以更简单的实现方式提供基本功能。
- 直接配置
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config",
"PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
"MCP_LOG_FILE": "/path/to/logs/debug.log",
"MCP_DEBUG": "1"
}
}
}
}
- 关键环境变量
MCP_LOG_FILE ：日志文件路径（建议避免标准输出污染）MCP_DEBUG ：设置为“1”以进行详细日志记录MCP_TEST_MOCK_MODE ：设置为“1”以使用模拟数据而不是真实集群KUBECONFIG ：Kubernetes 配置文件的路径KUBECTL_MCP_LOG_LEVEL ：设置为“DEBUG”、“INFO”、“WARNING”或“ERROR”
- 测试 MCP 服务器您可以使用以下方式测试服务器是否正常工作：
python -m kubectl_mcp_tool.simple_ping
python -m kubectl_mcp_tool
克劳德桌面
将以下内容添加到 Claude Desktop 配置的~/.config/claude/mcp.json （Windows： %APPDATA%\Claude\mcp.json ）：
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
光标人工智能
通过添加新的全局 MCP 服务器，将以下内容添加到 MCP 下的 Cursor AI 设置中：
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"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 配置的~/.config/windsurf/mcp.json （Windows： %APPDATA%\WindSurf\mcp.json ）：
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
自动配置
要自动配置所有支持的 AI 助手，请运行提供的安装脚本：
该脚本将：
- 安装所需的依赖项
- 为 Claude、Cursor 和 WindSurf 创建配置文件
- 设置正确的路径和环境变量
- 测试您的 Kubernetes 连接
先决条件
- kubectl 已安装并位于您的 PATH 中
- 有效的 kubeconfig 文件
- 访问 Kubernetes 集群
- Helm v3（可选，用于 Helm 操作）
示例
列出 Pod
List all pods in the default namespace
部署应用程序
Create a deployment named nginx-test with 3 replicas using the nginx:latest image
检查 Pod 日志
Get logs from the nginx-test pod
端口转发
Forward local port 8080 to port 80 on the nginx-test pod
发展
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server
# Install dependencies
pip install -r requirements.txt
# Install in development mode
pip install -e .
# Run the MCP server
python -m kubectl_mcp_tool
# Run tests
python -m python_tests.run_mcp_tests
项目结构
├── kubectl_mcp_tool/ # Main package
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Package entry point
│ ├── cli.py # CLI entry point
│ ├── mcp_server.py # MCP server implementation
│ ├── mcp_kubectl_tool.py # Main kubectl MCP tool implementation
│ ├── natural_language.py # Natural language processing
│ ├── diagnostics.py # Diagnostics functionality
│ ├── core/ # Core functionality
│ ├── security/ # Security operations
│ ├── monitoring/ # Monitoring functionality
│ ├── utils/ # Utility functions
│ └── cli/ # CLI functionality components
├── python_tests/ # Test suite
│ ├── run_mcp_tests.py # Test runner script
│ ├── mcp_client_simulator.py # MCP client simulator for mock testing
│ ├── test_utils.py # Test utilities
│ ├── test_mcp_core.py # Core MCP tests
│ ├── test_mcp_security.py # Security tests
│ ├── test_mcp_monitoring.py # Monitoring tests
│ ├── test_mcp_nlp.py # Natural language tests
│ ├── test_mcp_diagnostics.py # Diagnostics tests
│ └── mcp_test_strategy.md # Test strategy documentation
├── docs/ # Documentation
│ ├── README.md # Documentation overview
│ ├── INSTALLATION.md # Installation guide
│ ├── integration_guide.md # Integration guide
│ ├── cursor/ # Cursor integration docs
│ ├── windsurf/ # Windsurf integration docs
│ └── claude/ # Claude integration docs
├── compatible_servers/ # Compatible MCP server implementations
│ ├── cursor/ # Cursor-compatible servers
│ ├── windsurf/ # Windsurf-compatible servers
│ ├── minimal/ # Minimal server implementations
│ └── generic/ # Generic MCP servers
├── requirements.txt # Python dependencies
├── setup.py # Package setup script
├── pyproject.toml # Project configuration
├── MANIFEST.in # Package manifest
├── mcp_config.json # Sample MCP configuration
├── run_server.py # Server runner script
├── LICENSE # MIT License
├── CHANGELOG.md # Version history
├── .gitignore # Git ignore file
├── install.sh # Installation script
├── publish.sh # PyPI publishing script
└── start_mcp_server.sh # Server startup script
MCP 服务器工具
MCP 服务器实现（ kubectl_mcp_tool.mcp_server ）提供了一套全面的工具，可供 AI 助手使用与 Kubernetes 集群进行交互：
核心 Kubernetes 资源管理
- get_pods - 获取指定命名空间中的所有 pod
- get_namespaces - 获取所有 Kubernetes 命名空间
- get_services - 获取指定命名空间中的所有服务
- get_nodes - 获取集群中的所有节点
- get_configmaps - 获取指定命名空间中的所有 ConfigMap
- get_secrets - 获取指定命名空间中的所有 Secret
- get_deployments - 获取指定命名空间中的所有部署
- **create_deployment-**创建新的部署
- delete_resource - 删除 Kubernetes 资源
- get_api_resources - 列出 Kubernetes API 资源
- kubectl_explain - 使用 kubectl explain 解释 Kubernetes 资源
Helm 操作
- install_helm_chart - 安装 Helm 图表
- Upgrade_helm_chart - 升级 Helm 版本
- uninstall_helm_chart - 卸载 Helm 版本
安全运营
- get_rbac_roles - 获取指定命名空间中的所有 RBAC 角色
- get_cluster_roles - 获取所有集群范围的 RBAC 角色
监控和诊断
- get_events - 获取指定命名空间中的所有事件
- get_resource_usage - 通过 kubectl top 获取资源使用情况统计信息
- health_check - 通过 ping API 服务器检查集群健康状况
- get_pod_events - 获取特定 pod 的事件
- check_pod_health - 检查 pod 的健康状态
- get_logs - 从 pod 获取日志
集群管理
- switch_context - 切换当前 kubeconfig 上下文
- get_current_context - 获取当前 kubeconfig 上下文
- port_forward - 将本地端口转发到 pod 端口
- scale_deployment - 扩展部署
所有工具都返回包含成功/错误信息和相关详细信息的结构化数据，使 AI 助手能够轻松处理和理解响应。
贡献
欢迎贡献代码！欢迎提交 Pull 请求。
- 分叉存储库
- 创建你的功能分支（
git checkout -b feature/amazing-feature ） - 提交您的更改（
git commit -m 'Add some amazing feature' ） - 推送到分支（
git push origin feature/amazing-feature ） - 打开拉取请求
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。