Harvester MCP Server

Model Context Protocol (MCP) server for Harvester HCI that enables Claude Desktop, Cursor, and other AI assistants to interact with Harvester clusters through the MCP protocol.

Overview

Harvester MCP Server is a Go implementation of the Model Context Protocol (MCP) specifically designed for Harvester HCI. It allows AI assistants like Claude Desktop and Cursor to perform CRUD operations on Harvester clusters, which are essentially Kubernetes clusters with Harvester-specific CRDs.

Workflow

The following diagram illustrates how Harvester MCP Server bridges the gap between AI assistants and Harvester clusters:

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;

How It Works

1. LLM Integration: AI assistants like Claude Desktop and Cursor connect to Harvester MCP Server via the MCP protocol.
2. Request Processing: The MCP Server receives natural language requests from the AI assistants and translates them into specific Kubernetes operations.
3. Resource Handling: The Resource Handler identifies the resource type and operation being requested.
4. Formatter Selection: The Formatter Registry selects the appropriate formatter for the resource type.
5. API Interaction: The server interacts with the Kubernetes API of the Harvester cluster.
6. Response Formatting: Results are formatted into human-readable text optimized for LLM consumption.
7. User Presentation: Formatted responses are returned to the AI assistant to present to the user.

This architecture enables AI assistants to interact with Harvester clusters through natural language, making complex Kubernetes operations more accessible to users.

Features

• Kubernetes Core Resources:

  • Pods: List, Get, Delete
  • Deployments: List, Get
  • Services: List, Get
  • Namespaces: List, Get
  • Nodes: List, Get
  • Custom Resource Definitions (CRDs): List

• Harvester-Specific Resources:

  • Virtual Machines: List, Get
  • Images: List
  • Volumes: List
  • Networks: List

• Enhanced User Experience:

  • Human-readable formatted outputs for all resources
  • Automatic grouping of resources by namespace or status
  • Concise summaries with the most relevant information
  • Detailed views for comprehensive resource inspection

Requirements

• Go 1.23+
• Access to a Harvester cluster with a valid kubeconfig

Installation

From Source

# 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

Using Go Install

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

Configuration

The server automatically looks for Kubernetes configuration in the following order:

1. In-cluster configuration (if running inside a Kubernetes cluster)
2. Path specified by the --kubeconfig flag
3. Path specified by the KUBECONFIG environment variable
4. Default location at ~/.kube/config

Command-Line Flags

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

Examples

Using a specific kubeconfig file:

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

Using the KUBECONFIG environment variable:

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

With debug logging:

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

Usage with Claude Desktop

1. Install Claude Desktop
2. Open Claude Desktop configuration file (~/Library/Application\ Support/Claude/claude_desktop_config.json or similar)
3. Add the Harvester MCP server to the mcpServers section:

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

4. Restart Claude Desktop
5. The Harvester MCP tools should now be available to Claude

Example Queries for Claude Desktop

Once your Harvester MCP server is configured in Claude Desktop, you can ask questions like:

• "How many nodes are in my Harvester cluster?"
• "List all pods in the cattle-system namespace"
• "Show me the details of the pod named rancher-789c976c6-xbvmd in cattle-system namespace"
• "List all virtual machines in the default namespace"
• "What services are running in the harvester-system namespace?"

Development

Project Structure

• cmd/harvester-mcp-server: Main application entry point
• pkg/client: Kubernetes client implementation
• pkg/cmd: CLI commands implementation using Cobra
• pkg/mcp: MCP server implementation
• pkg/kubernetes: Unified resource handlers for Kubernetes resources
• pkg/tools: Legacy tool implementations for interacting with Harvester resources

Resource Handling

The project uses a unified approach to handle Kubernetes resources:

1. The pkg/kubernetes/resources.go file contains a ResourceHandler that provides common operations for all resource types:

   • Listing resources with proper namespace handling
   • Getting resource details by name
   • Creating and updating resources
   • Deleting resources

2. The pkg/kubernetes/formatters*.go files contain formatters for different resource types:

   • Each formatter converts raw Kubernetes objects into human-readable text
   • Resource-specific details are extracted and formatted in a consistent way
   • Custom formatters exist for both standard Kubernetes resources and Harvester-specific resources

3. The pkg/kubernetes/types.go file maps friendly resource type names to Kubernetes GroupVersionResource objects:

   • Makes it easy to refer to resources by simple names in code
   • Centralizes resource type definitions

Adding New Tools

To add a new tool:

1. If it's a new resource type, add it to pkg/kubernetes/types.go
2. Implement formatters for the resource in one of the formatter files
3. Register the tool in pkg/mcp/server.go in the registerTools method using the unified resource handler

Formatting Functions

Each resource type has two formatting functions:

1. formatXList - Formats a list of resources with concise information, grouped by namespace
2. formatX - Formats a single resource with detailed information

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Harvester HCI - The foundation for this project
• mark3labs/mcp-go - The Go SDK for Model Context Protocol
• manusa/kubernetes-mcp-server - Reference implementation for Kubernetes MCP server