Kubectl MCP 工具

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

⚠️ 已知问题

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

• Claude
• Cursor
• Windsurf

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

在此期间，您的耐心和支持非常宝贵。🙏

感谢您的理解！

特性

核心 Kubernetes 操作

• 连接到 Kubernetes 集群
• 列出和管理 Pod、服务、部署和节点
• 创建、删除和描述 Pod 及其他资源
• 获取 Pod 日志和 Kubernetes 事件
• 支持 Helm v3 操作（安装、升级、卸载）
• kubectl explain 和 api-resources 支持
• 为下一个命令选择命名空间（内存持久化）
• 端口转发到 Pod
• 扩展部署和有状态集
• 在容器中执行命令
• 管理 ConfigMaps 和 Secrets
• 回滚部署到以前的版本
• Ingress 和 NetworkPolicy 管理
• 在集群之间切换上下文

自然语言处理

• 处理针对 kubectl 操作的自然语言查询
• 具有前序操作记忆的上下文感知命令
• 以人类友好的方式解释 Kubernetes 概念
• 从意图智能构建命令
• 当没有专门工具可用时回退到 kubectl
• 支持离线/测试场景的模拟数据
• 命名空间感知的查询处理

监控

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

安全

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

诊断

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

高级功能

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

架构

模型上下文协议 (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 包管理器)

全局安装

# 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服务器。

与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

在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以供全局设置使用。

注意：请用实际的kubeconfig文件路径替换/path/to/your/.kube/config。在大多数系统上，该路径为~/.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操作）

示例

列出Pods

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 tests
python -m python_tests.test_all_features

项目结构

├── kubectl_mcp_tool/         # Main package
│   ├── __init__.py           # Package initialization
│   ├── 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
├── 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

贡献

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

1. 分叉仓库
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文件。