Harvester MCP Server

Harvester MCP 服务

重要

这是一个社区项目，不受 Harvester 官方支持。如果你正在寻找 Harvester 官方支持的 MCP 服务，请使用 harvester/harvester-mcp-server。

适用于 Harvester HCI 的 Model Context Protocol（MCP）服务，可让 Claude Desktop、Cursor 和其他 AI 助手通过 MCP 协议与 Harvester 集群交互。

概述

Harvester MCP Server 是一个专为 Harvester HCI 设计的 Go 语言实现的 Model Context Protocol（MCP） 服务。它允许 Claude Desktop 和 Cursor 等 AI 助手对 Harvester 集群执行 CRUD 操作。Harvester 集群本质上是带有 Harvester 专用 CRD 的 Kubernetes 集群。

工作流

下图展示了 Harvester MCP Server 如何搭建 AI 助手与 Harvester 集群之间的桥梁：

graph LR;
    subgraph "AI Assistants"
        A[Claude Desktop] --> C[MCP Client];
        B[Cursor IDE] --> C;
    end
    
    subgraph "Harvester MCP Server"
        C --> D[MCP Server];
        D --> E[Resource Handler];
        E --> F[Formatter Registry];
        F -->|Get Formatter| G[Core Resource Formatters];
        F -->|Get Formatter| H[Harvester Resource Formatters];
    end
    
    subgraph "Kubernetes / Harvester"
        G --> I[Kubernetes API];
        H --> I;
        I --> J[Harvester Cluster];
    end
    
    style A fill:#f9f,stroke:#333,stroke-width:2px;
    style B fill:#f9f,stroke:#333,stroke-width:2px;
    style D fill:#bbf,stroke:#333,stroke-width:2px;
    style J fill:#bfb,stroke:#333,stroke-width:2px;

工作原理

1. LLM 集成：Claude Desktop 和 Cursor 等 AI 助手通过 MCP 协议连接到 Harvester MCP Server。
2. 请求处理：MCP Server 接收 AI 助手的自然语言请求，并将其转换为具体的 Kubernetes 操作。
3. 资源处理：资源处理器识别请求涉及的资源类型和操作。
4. 格式化器选择：格式化器注册表为相应的资源类型选择合适的格式化器。
5. API 交互：服务与 Harvester 集群的 Kubernetes API 交互。
6. 响应格式化：将结果格式化为便于大模型理解的易读文本。
7. 向用户展示：将格式化后的响应返回给 AI 助手，以便向用户展示。

这种架构让 AI 助手能够通过自然语言与 Harvester 集群交互，使用户更容易执行复杂的 Kubernetes 操作。

功能

• Kubernetes 核心资源：

  • Pod：列表、获取、删除
  • Deployment：列表、获取
  • Service：列表、获取
  • Namespace：列表、获取
  • Node：列表、获取
  • 自定义资源定义（CRD）：列表

• Harvester 专用资源：

  • 虚拟机：列表、获取
  • 镜像：列表
  • 卷：列表
  • 网络：列表

• 增强的用户体验：

  • 为所有资源提供易读的格式化输出
  • 按命名空间或状态自动对资源分组
  • 简明摘要，突出最相关的信息
  • 提供详细视图，全面检查资源

要求

• Go 1.23+
• 可通过有效的 kubeconfig 访问 Harvester 集群

安装

从源代码安装

# Clone the repository
git clone https://github.com/starbops/harvester-mcp-server.git
cd harvester-mcp-server

# Build
make build

# Run
./bin/harvester-mcp-server

使用 Go Install 安装

go install github.com/starbops/harvester-mcp-server/cmd/harvester-mcp-server@latest

配置

服务会按以下顺序自动查找 Kubernetes 配置：

1. 集群内配置（在 Kubernetes 集群内部运行时）
2. --kubeconfig 标志指定的路径
3. KUBECONFIG 环境变量指定的路径
4. 默认位置 ~/.kube/config

命令行标志

Usage:
  harvester-mcp-server [flags]

Flags:
  -h, --help                help for harvester-mcp-server
      --kubeconfig string   Path to the kubeconfig file (default is $KUBECONFIG or $HOME/.kube/config)
      --log-level string    Log level (debug, info, warn, error, fatal, panic) (default "info")

示例

使用指定的 kubeconfig 文件：

harvester-mcp-server --kubeconfig=/path/to/kubeconfig.yaml

使用 KUBECONFIG 环境变量：

export KUBECONFIG=$HOME/config.yaml
harvester-mcp-server

启用调试日志：

harvester-mcp-server --log-level=debug

与 Claude Desktop 搭配使用

1. 安装 Claude Desktop
2. 打开 Claude Desktop 配置文件（~/Library/Application\ Support/Claude/claude_desktop_config.json 或类似路径）
3. 在 mcpServers 部分添加 Harvester MCP 服务：

{
  "mcpServers": {
    "harvester": {
      "command": "/path/to/harvester-mcp-server",
      "args": ["--kubeconfig", "/path/to/kubeconfig.yaml", "--log-level", "info"]
    }
  }
}

4. 重启 Claude Desktop
5. Claude 现在应该可以使用 Harvester MCP 工具

Claude Desktop 示例查询

在 Claude Desktop 中配置 Harvester MCP 服务后，你可以询问：

• “我的 Harvester 集群中有多少个节点？”
• “列出 cattle-system 命名空间中的所有 Pod”
• “显示 cattle-system 命名空间中名为 rancher-789c976c6-xbvmd 的 Pod 的详细信息”
• “列出 default 命名空间中的所有虚拟机”
• “harvester-system 命名空间中正在运行哪些服务？”

开发

项目结构

• cmd/harvester-mcp-server：应用程序主入口
• pkg/client：Kubernetes 客户端实现
• pkg/cmd：使用 Cobra 实现的 CLI 命令
• pkg/mcp：MCP 服务实现
• pkg/kubernetes：Kubernetes 资源的统一处理程序
• pkg/tools：用于与 Harvester 资源交互的旧版工具实现

资源处理

项目采用统一的方式处理 Kubernetes 资源：

1. pkg/kubernetes/resources.go 文件包含一个 ResourceHandler，为所有资源类型提供通用操作：

   • 列出资源，并正确处理命名空间
   • 按名称获取资源详情
   • 创建和更新资源
   • 删除资源

2. pkg/kubernetes/formatters*.go 文件包含针对不同资源类型的格式化器：

   • 每个格式化器都会将原始 Kubernetes 对象转换为易读文本
   • 以一致的方式提取并格式化特定资源的详情
   • 标准 Kubernetes 资源和 Harvester 专属资源均有自定义格式化器

3. pkg/kubernetes/types.go 文件将便于识别的资源类型名称映射到 Kubernetes GroupVersionResource 对象：

   • 便于在代码中使用简单名称引用资源
   • 集中定义资源类型

添加新工具

添加新工具的步骤：

1. 如果是新的资源类型，将其添加到 pkg/kubernetes/types.go
2. 在某个格式化器文件中为该资源实现格式化器
3. 在 pkg/mcp/server.go 的 registerTools 方法中，使用统一资源处理程序注册该工具

格式化函数

每种资源类型都有两个格式化函数：

1. formatXList：按命名空间分组，使用简洁信息格式化资源列表
2. formatX：使用详细信息格式化单个资源

许可证

本项目采用 Apache License 2.0 许可协议，详情请参阅 LICENSE 文件。

致谢

• Harvester HCI - 本项目的基础
• mark3labs/mcp-go - Model Context Protocol 的 Go SDK
• manusa/kubernetes-mcp-server - Kubernetes MCP 服务的参考实现