STARWARCLOUD STARWAR.AI
返回市场
kubectl-MCP服务器

kubectl-MCP服务器

作者：rohitg00736 星标更新：2025-07-15
安装使用来源：spider==github.com

项目介绍

Kubectl MCP Server

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

License: MIT Python Kubernetes MCP PyPI version

🎥 实时演示 - 观看Claude使用kubectl-mcp-tool！

Claude MCP

🎥 实时演示 - 观看Cursor使用kubectl-mcp-tool！

Cursor MCP

🎥 实时演示 - 观看Windsurf使用kubectl-mcp-tool！

Windsurf MCP

功能

核心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.1

该包在PyPI上可用：https://pypi.org/project/kubectl-mcp-tool/1.1.1/

先决条件

  • 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 .

验证安装

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

kubectl-mcp --help

注意：此工具设计为AI助手连接的MCP服务器，而不是直接替代kubectl。主要命令是kubectl-mcp serve，它启动MCP服务器。

Docker镜像

如果你更喜欢使用Docker，可以在Docker Hub上找到预构建的镜像：

# 拉取最新镜像
docker pull rohitghumare64/kubectl-mcp-server:latest

运行镜像

容器内的服务器监听端口8000。将主机上的任意空闲端口绑定到8000，并挂载你的kubeconfig：

# 将8081替换为你主机上的任意空闲端口
# 挂载你的本地~/.kube目录以访问集群凭证

docker run -p 8081:8000 \
           -v $HOME/.kube:/root/.kube \
           rohitghumare64/kubectl-mcp-server:latest
  • -p 8081:8000 将主机端口8081映射到容器端口8000。
  • -v $HOME/.kube:/root/.kube 挂载你的kubeconfig以便服务器可以访问集群。

构建多架构镜像（AMD64 & ARM64）

如果你想构建并推送一个多架构镜像（使其能在x86_64和Apple Silicon上运行），可以使用Docker Buildx：

# 确保每台机器上Buildx和QEMU已安装一次
# docker buildx create --name multiarch --use
# docker buildx inspect --bootstrap

# 构建并推送linux/amd64和linux/arm64
# （如果发布到自己的注册表，请替换<your_username>）

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t rohitghumare64/kubectl-mcp-server:latest \
  --push .

发布的镜像将包含两个架构的清单列表，Docker会自动在每台机器上拉取正确的变体。

配置

MCP服务器允许访问以下路径来读取你的Kubernetes配置：

run:
  volumes:
    - '{{kubectl-mcp-server.kubeconfig}}:/root/.kube'
config:
  description: MCP服务器允许访问此路径
  parameters:
    type: object
    properties:
      kubeconfig:
        type: string
        default:
          $HOME/.kube
    required:
      - kubeconfig

此配置允许用户将他们的kubeconfig目录添加到容器中，使MCP服务器能够与其Kubernetes集群进行身份验证。

使用AI助手

使用MCP服务器

MCP服务器（kubectl_mcp_tool.mcp_server）是一个基于FastMCP SDK的强大实现，提供了跨不同AI助手的增强兼容性：

注意：如果你遇到MCP服务器实现中的任何错误，可以通过在配置中将kubectl_mcp_tool.mcp_server替换为kubectl_mcp_tool.minimal_wrapper来回退到最小包装器。最小包装器提供了基本功能，但实现更为简单。

  1. 直接配置

    {
  "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"
      }
    }
  }
}

  2. 关键环境变量

    • MCP_LOG_FILE：日志文件路径（推荐避免stdout污染）
    • MCP_DEBUG：设置为"1"启用详细日志
    • MCP_TEST_MOCK_MODE：设置为"1"使用模拟数据而非真实集群
    • KUBECONFIG：Kubernetes配置文件路径
    • KUBECTL_MCP_LOG_LEVEL：设置为"DEBUG"、"INFO"、"WARNING"或"ERROR"

  3. 测试MCP服务器 你可以通过以下命令测试服务器是否正常工作：

    python -m kubectl_mcp_tool.simple_ping

    这将尝试连接到服务器并执行ping命令。

    或者，你可以直接运行服务器：

    python -m kubectl_mcp_tool

Claude桌面

在Claude桌面配置~/Library/Application\ Support/Claude/claude_desktop_config.json（Windows：%APPDATA%\Claude\mcp.json）中添加以下内容：

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.mcp_server"], 
      "env": {
        "KUBECONFIG": "$HOME/.kube/config" // 或者你的配置文件的实际路径
      }
    }
  }
}

Cursor AI

在Cursor AI设置下的MCP中添加一个新的全局MCP服务器：

{
  "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

在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助手，运行提供的安装脚本：

bash install.sh