mcp-k8s

mcp-k8s

一个 Kubernetes MCP（模型控制协议）服务，可通过 MCP 工具与 Kubernetes 集群交互。

功能

• 查询支持的 Kubernetes 资源类型（内置资源和 CRD）
• 精细控制 Kubernetes 资源操作
  • 读取操作：获取资源详情、按类型列出资源并进行筛选
  • 写入操作：创建、更新和删除资源（每项操作均可独立启用或禁用）
  • 支持所有 Kubernetes 资源类型，包括自定义资源
• 使用 kubeconfig 连接 Kubernetes 集群
• 精细控制 Helm
  • Helm 发行版管理（列出、获取、安装、升级、卸载）
  • Helm 仓库管理（列出、添加、移除）
  • 每项操作均可独立启用或禁用

预览

通过 cursor 交互

使用场景

1. 通过大模型管理 Kubernetes 资源

• 交互式资源管理：通过自然语言与大模型交互来管理 Kubernetes 资源，无需记忆复杂的 kubectl 命令
• 批量操作：用自然语言描述复杂的批量操作需求，让大模型将其转换为具体的资源操作
• 资源状态查询：使用自然语言查询集群资源状态，并获取通俗易懂的回答

2. 自动化运维场景

• 智能运维助手：作为运维人员日常集群管理任务的智能助手
• 问题诊断：通过自然语言描述问题，协助诊断集群问题
• 配置审查：利用大模型的理解能力，帮助审查和优化 Kubernetes 资源配置

3. 开发与测试支持

• 快速原型验证：开发者可以通过自然语言快速创建和验证资源配置
• 环境管理：简化测试环境的资源管理，快速创建、修改和清理测试资源
• 配置生成：根据需求描述，自动生成符合最佳实践的资源配置

4. 教育与培训场景

• 交互式学习：新人可以通过自然语言交互学习 Kubernetes 概念和操作
• 最佳实践指导：在资源操作过程中，大模型会提供最佳实践建议
• 错误说明：操作失败时，提供通俗易懂的错误说明和修正建议

架构

1. 项目概述

一个基于 stdio 的 MCP 服务，可连接 Kubernetes 集群并提供以下能力：

• 查询 Kubernetes 资源类型（包括内置资源和 CRD）
• 对 Kubernetes 资源执行 CRUD 操作（写入操作可配置）
• 执行 Helm 操作以管理发行版和仓库

2. 技术栈

• Go
• mcp-go SDK
• Kubernetes client-go 库
• Helm v3 客户端库
• 使用 Stdio 进行通信

3. 核心组件

1. MCP 服务：使用 mcp-go 的 mcp-k8s 包创建基于 stdio 的 MCP 服务
2. K8s 客户端：使用 client-go 连接 Kubernetes 集群
3. Helm 客户端：使用 Helm v3 库执行 Helm 操作
4. 工具实现：实现用于执行各种 Kubernetes 操作的 MCP 工具

4. 可用工具

资源类型查询工具

• get_api_resources：获取集群中所有受支持的 API 资源类型

资源操作工具

• get_resource：获取特定资源的详细信息
• list_resources：列出某一资源类型的所有实例
• create_resource：创建新资源（可禁用）
• update_resource：更新现有资源（可禁用）
• delete_resource：删除资源（可禁用）

Helm 操作工具

• list_helm_releases：列出集群中的所有 Helm 发布版本
• get_helm_release：获取特定 Helm 发布版本的详细信息
• install_helm_chart：安装 Helm Chart（可禁用）
• upgrade_helm_chart：升级 Helm 发布版本（可禁用）
• uninstall_helm_chart：卸载 Helm 发布版本（可禁用）
• list_helm_repositories：列出已配置的 Helm 仓库
• add_helm_repository：添加新的 Helm 仓库（可禁用）
• remove_helm_repository：移除 Helm 仓库（可禁用）

使用方法

mcp-k8s 支持三种通信模式：

1. Stdio 模式（默认）

在 stdio 模式下，mcp-k8s 通过标准输入/输出流与客户端通信。这是默认模式，适用于大多数使用场景。

# Run in stdio mode (default)
{
    "mcpServers":
    {
        "mcp-k8s":
        {
            "command": "/path/to/mcp-k8s",
            "args":
            [
                "--kubeconfig",
                "/path/to/kubeconfig",
                "--enable-create",
                "--enable-delete",
                "--enable-update",
                "--enable-list",
                "--enable-helm-install",
                "--enable-helm-upgrade"
            ]
        }
    }
}

2. SSE 模式

在 SSE（Server-Sent Events，服务器发送事件）模式下，mcp-k8s 会向 MCP 客户端公开一个 HTTP 端点。 你可以将服务部署在远程服务上（但需注意安全）

# Run in SSE mode
./bin/mcp-k8s --kubeconfig=/path/to/kubeconfig --transport=sse --port=8080 --host=localhost --enable-create --enable-delete --enable-list --enable-update --enable-helm-install
# This command will open all operations

mcp 配置

{
  "mcpServers": {
    "mcp-k8s": {
      "url": "http://localhost:8080/sse",
      "args": []
    }
  }
}

SSE 模式配置：

• --transport：设为 "sse" 以启用 SSE 模式
• --port：HTTP 服务端口（默认：8080）
• --host：HTTP 服务主机（默认："localhost"）

3. Streamable HTTP 模式

在 Streamable HTTP 模式下，mcp-k8s 会公开一个 HTTP 端点，同时支持直接 HTTP 响应和 SSE 流。此模式灵活性更高，并支持流式输出。

# Run in Streamable HTTP mode
./bin/mcp-k8s --kubeconfig=/path/to/kubeconfig --transport=streamable-http --port=8080 --host=localhost --endpoint-path=/mcp --enable-create --enable-delete --enable-list --enable-update --enable-helm-install

mcp 配置

{
  "mcpServers": {
    "mcp-k8s": {
      "url": "http://localhost:8080/mcp",
      "args": []
    }
  }
}

Streamable HTTP 模式配置：

• --transport：设为 "streamable-http" 以启用 Streamable HTTP 模式
• --port：HTTP 服务端口（默认：8080）
• --host：HTTP 服务主机（默认："localhost"）
• --endpoint-path：MCP 服务的端点路径（默认："/mcp"）

4. Docker 环境

SSE 模式

1. 完整示例 假设你的镜像名称为 mcp-k8s，且需要映射端口并设置环境参数，你可以运行：

docker run --rm -p 8080:8080 -i -v ~/.kube/config:/root/.kube/config ghcr.io/silenceper/mcp-k8s:latest --transport=sse

Streamable HTTP 模式

docker run --rm -p 8080:8080 -i -v ~/.kube/config:/root/.kube/config ghcr.io/silenceper/mcp-k8s:latest --transport=streamable-http --endpoint-path=/mcp

stdio 模式

{
  "mcpServers": {
    "mcp-k8s": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-v",
        "~/.kube/config:/root/.kube/config",
        "--rm",
        "ghcr.io/silenceper/mcp-k8s:latest"
      ]
    }
  }
}

开始使用

直接使用

你可以从 发布页面 直接下载适用于你平台的二进制文件并立即使用。

Go 安装

go install github.com/silenceper/mcp-k8s/cmd/mcp-k8s@latest

构建

使用 Makefile（推荐）

Makefile 会自动从 VERSION 文件注入版本信息：

git clone https://github.com/silenceper/mcp-k8s.git
cd mcp-k8s
make build

此操作会通过 ldflags 注入版本信息并进行构建。

直接构建

git clone https://github.com/silenceper/mcp-k8s.git
cd mcp-k8s
go build -o bin/mcp-k8s cmd/mcp-k8s/main.go

注意：除非手动指定 ldflags，否则直接构建会显示版本为 "dev"。

命令行参数

你可以使用 mcp-k8s --help 查看所有可用选项，或使用 mcp-k8s --version 检查版本。

Kubernetes 资源操作

• --kubeconfig：Kubernetes 配置文件的路径（未指定时使用默认配置）
• --enable-create：启用资源创建操作（默认：false）
• --enable-update：启用资源更新操作（默认：false）
• --enable-delete：启用资源删除操作（默认：false）
• --enable-list：启用资源列表操作（默认：true）

Helm 操作

• --enable-helm-release-list：启用 Helm 发布版本列表操作（默认值：true）
• --enable-helm-release-get：启用 Helm 发布版本获取操作（默认值：true）
• --enable-helm-install：启用 Helm chart 安装（默认值：false）
• --enable-helm-upgrade：启用 Helm chart 升级（默认值：false）
• --enable-helm-uninstall：启用 Helm chart 卸载（默认值：false）
• --enable-helm-repo-list：启用 Helm 仓库列表操作（默认值：true）
• --enable-helm-repo-add：启用 Helm 仓库添加操作（默认值：false）
• --enable-helm-repo-remove：启用 Helm 仓库移除操作（默认值：false）

传输配置

• --transport：传输类型（stdio、sse 或 streamable-http）（默认值："stdio"）
• --host：HTTP 传输的主机（SSE 或 Streamable HTTP）（默认值："localhost"）
• --port：HTTP 传输的 TCP 端口（SSE 或 Streamable HTTP）（默认值：8080）
• --endpoint-path：Streamable HTTP 传输的端点路径（默认值："/mcp"）

版本信息

• --version：显示版本信息，包括版本号、提交哈希和构建日期
• --help 或 -h：显示帮助信息

测试 Streamable HTTP

要测试 Streamable HTTP 模式是否正常运行，可以使用提供的测试脚本：

# Start the server in one terminal
./bin/mcp-k8s --transport=streamable-http --port=8080 --enable-list

# In another terminal, run the test script
./test_streamable_http.sh

详细测试说明请参阅 TEST_STREAMABLE_HTTP.md。

与 MCP 客户端集成

mcp-k8s 是基于 stdio 的 MCP 服务，可与任何兼容 MCP 的大模型客户端集成。有关集成说明，请参阅 MCP 客户端的文档。

安全注意事项

• 写入操作通过独立的配置开关进行严格控制
• 使用 RBAC 确保 K8s 客户端仅拥有必要的权限
• 验证所有用户输入，以防止注入攻击
• Helm 操作遵循相同的安全原则，默认启用读取操作，默认禁用写入操作

关注微信公众号