Kubernetes MCP Server

# MCP Kubernetes Server 一个基于 [FastMCP](https://github.com/jlowin/fastmcp) 框架构建的 Kubernetes 管理服务器，提供完整的 Kubernetes 集群管理功能。 ## 🚀 项目特性 - **完整的 Kubernetes 管理**: 支持 kubectl 的所有核心操作 - **Helm 集成**: 提供 Helm Chart 的安装、升级、卸载功能 - **多种传输方式**: 支持 HTTP 和 STDIO 两种传输协议 - **灵活的配置**: 支持多种 kubeconfig 配置方式 - **安全性**: 自动屏蔽 Secret 敏感数据 - **故障诊断**: 内置 Kubernetes 故障诊断助手 - **健康检查**: 提供服务健康状态监控 ## 📁 项目结构 ``` MCP/ ├── core/ │ └── kubernetes_mcp_core.py # 核心模块：包含所有工具函数实现 ├── httpserver.py # HTTP 传输版本的 MCP 服务器 ├── stdio.py # STDIO 传输版本的 MCP 服务器 ├── simple_mcp_test.py # 简单的测试客户端 ├── pyproject.toml # 项目配置和依赖管理 ├── VERSION # 版本信息 └── README.md # 项目文档 ``` ### 核心架构 - **`core/kubernetes_mcp_core.py`**: 核心模块，包含所有 Kubernetes 和 Helm 操作的实现 - **`httpserver.py`**: HTTP 传输模式的服务器入口 - **`stdio.py`**: STDIO 传输模式的服务器入口（现在支持完整功能） ## 🛠️ 安装与配置 ### 环境要求 - Python 3.10+ - kubectl (必需) - helm (可选，用于 Helm 功能) - 有效的 Kubernetes 集群访问权限 ### 安装依赖 项目使用 `uv` 作为包管理器： ```bash # 安装依赖 uv sync # 开发环境依赖 uv sync --dev ``` ### Kubernetes 配置 服务器支持多种 kubeconfig 配置方式，按优先级排序： 1. **YAML 环境变量**: ```bash export KUBECONFIG_YAML="$(cat ~/.kube/config)" ``` 2. **JSON 环境变量**: ```bash export KUBECONFIG_JSON='{"apiVersion":"v1","kind":"Config",...}' ``` 3. **最小配置**: ```bash export K8S_SERVER="https://your-k8s-api-server" export K8S_TOKEN="your-service-account-token" export K8S_SKIP_TLS_VERIFY="true" # 可选 ``` 4. **标准路径**: ```bash export KUBECONFIG="/path/to/your/kubeconfig" # 或使用默认路径 ~/.kube/config ``` ### 其他配置选项 ```bash # 设置默认上下文 export K8S_CONTEXT="your-context-name" # 设置默认命名空间 export K8S_NAMESPACE="your-namespace" # 控制 Secret 数据屏蔽（默认启用） export MASK_SECRETS="true" ``` ## 🚀 运行服务器 ### HTTP 传输模式 适用于需要 HTTP API 访问的场景： ```bash uv run httpserver.py ``` 服务器将在 `http://127.0.0.1:6000` 启动。 ### STDIO 传输模式 适用于 MCP 客户端（如 Cherry Studio）： ```bash uv run stdio.py ``` ## 🔧 可用工具 ### 核心 Kubernetes 操作 - **`ping`**: 验证与 Kubernetes 集群的连接 - **`kubectl_get`**: 获取或列出 Kubernetes 资源 - **`kubectl_describe`**: 描述资源的详细信息 - **`kubectl_apply`**: 应用 YAML 清单 - **`kubectl_delete`**: 删除 Kubernetes 资源 - **`kubectl_logs`**: 获取资源日志 - **`kubectl_context`**: 管理 Kubernetes 上下文 - **`kubectl_scale`**: 扩缩容资源 - **`kubectl_patch`**: 更新资源字段 - **`kubectl_rollout`**: 管理滚动更新 - **`kubectl_exec`**: 在 Pod 中执行命令 ### Helm 操作 - **`helm_install`**: 安装 Helm Chart - **`helm_upgrade`**: 升级 Helm Release - **`helm_uninstall`**: 卸载 Helm Release - **`helm_list`**: 列出 Helm Releases ### 辅助功能 - **`health_check`**: 健康检查端点 ## 📚 资源和提示符 ### 资源 - **`k8s://cluster/info`**: 获取集群信息 - **`k8s://contexts`**: 获取可用上下文 ### 提示符 - **`k8s_diagnose`**: Kubernetes 故障诊断助手 ## 🧪 测试 使用提供的测试客户端验证服务器功能： ```bash # 确保 HTTP 服务器正在运行 uv run simple_mcp_test.py ``` ## 🏗️ 架构设计 ### 模块化架构 项目采用模块化设计，将核心功能与传输层分离： - **核心模块** (`core/kubernetes_mcp_core.py`): 包含所有业务逻辑和工具实现 - **传输层** (`httpserver.py`, `stdio.py`): 负责不同的通信协议 ### 优势 1. **代码复用**: 两种传输模式共享相同的核心功能 2. **易于维护**: 业务逻辑集中在核心模块中 3. **功能一致**: STDIO 和 HTTP 版本提供完全相同的功能 4. **扩展性**: 可以轻松添加新的传输模式 5. **清晰分层**: 核心逻辑与传输协议完全分离 ### 设计原则 - **单一职责**: 每个模块都有明确的职责边界 - **依赖倒置**: 传输层依赖于核心模块，而非相反 - **开放封闭**: 对扩展开放（新传输模式），对修改封闭（核心逻辑） ## 📖 使用示例 ### 基本操作示例 ```python from fastmcp import Client import asyncio async def example(): async with Client("http://127.0.0.1:6000/mcp") as client: # 检查连接 result = await client.call_tool("ping") print(result) # 获取所有 Pod pods = await client.call_tool("kubectl_get", { "resource_type": "pods", "all_namespaces": True }) print(pods) # 获取特定 Deployment 的日志 logs = await client.call_tool("kubectl_logs", { "resource_type": "deployment", "name": "my-app", "namespace": "default", "tail": 100 }) print(logs) asyncio.run(example()) ``` ### 使用 Helm ```python # 安装 Chart await client.call_tool("helm_install", { "name": "my-release", "chart": "stable/nginx", "namespace": "default", "values": { "replicaCount": 3, "service": { "type": "LoadBalancer" } } }) ``` ## 🔒 安全特性 - **Secret 数据屏蔽**: 自动屏蔽 Kubernetes Secret 中的敏感数据 - **超时控制**: 所有 kubectl 和 helm 命令都有超时限制 - **错误处理**: 完善的错误处理和日志记录 ## 🐛 故障排除 ### 常见问题 1. **kubectl 未找到**: ```bash # 确保 kubectl 已安装并在 PATH 中 kubectl version --client ``` 2. **连接失败**: ```bash # 检查 kubeconfig 配置 kubectl cluster-info ``` 3. **权限问题**: ```bash # 检查当前用户权限 kubectl auth can-i --list ``` ### 日志调试 服务器启动时会显示配置信息： ``` 启动Kubernetes MCP服务器... 配置信息: - kubeconfig路径: /home/user/.kube/config - 默认命名空间: default - 上下文: my-context ``` ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ ## 📄 许可证 本项目采用 MIT 许可证。 ## 🔗 相关链接 - [FastMCP 框架](https://github.com/jlowin/fastmcp) - [Kubernetes 官方文档](https://kubernetes.io/docs/) - [Helm 官方文档](https://helm.sh/docs/) - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)