lyarwood/kubevirt-mcp-server

kubevirt-mcp-server

A simple Model Context Protocol server for KubeVirt.

Architecture

The project is organized into modular packages:

• main.go - MCP server setup and registration
• pkg/client/ - Shared KubeVirt client utilities
• pkg/tools/ - MCP tool handlers for VM operations
• pkg/resources/ - MCP resource handlers for structured data access
• scripts/kubevirtci.sh - Script for managing local kubevirtci development environment
• scripts/sync.sh - Script for building and running MCP server locally with kubevirtci access
• Makefile - Build automation and development tasks

Features

MCP Tools

• list_vms - List virtual machine names in a namespace
• start_vm - Start a virtual machine
• stop_vm - Stop a virtual machine
• restart_vm - Restart a virtual machine (handles both running and stopped VMs)
• pause_vm - Pause a virtual machine
• unpause_vm - Unpause a virtual machine
• create_vm - Create a virtual machine with specified container disk (supports OS name lookup), optional instancetype and preference
• delete_vm - Delete a virtual machine
• patch_vm - Apply JSON merge patch to modify VM configuration
• list_instancetypes - List available instance types
• get_instancetype - Get detailed information about a specific instance type
• get_preference - Get detailed information about a specific preference
• get_vm_instancetype - Get instance type for a VM
• get_vm_status - Get comprehensive VM status information
• get_vm_conditions - Get detailed VM condition information
• get_vm_phase - Get current VM phase and basic status
• get_vm_disks - Retrieve the list of disks attached to a virtual machine

MCP Prompts

• describe_vm - Provide comprehensive VM description including configuration, status, and operational details
• troubleshoot_vm - Diagnose and analyze potential VM issues with actionable recommendations
• health_check_vm - Perform quick VM health check and report issues

MCP Resources

• kubevirt://{namespace}/vms - JSON list of VMs with summary info
• kubevirt://{namespace}/vm/{name} - Complete VM specification
• kubevirt://{namespace}/vm/{name}/status - VM status and phase information
• kubevirt://{namespace}/vm/{name}/console - VM console connection details
• kubevirt://{namespace}/vmis - JSON list of VMIs with runtime info
• kubevirt://{namespace}/vmi/{name} - Complete VMI specification
• kubevirt://{namespace}/vmi/{name}/guestosinfo - VMI guest OS information
• kubevirt://{namespace}/vmi/{name}/filesystems - VMI filesystem information
• kubevirt://{namespace}/vmi/{name}/userlist - VMI user list information
• kubevirt://{namespace}/datavolumes - JSON list of DataVolumes with source and storage info
• kubevirt://{namespace}/datavolume/{name} - Complete DataVolume specification
• kubevirt://{namespace}/instancetypes - Namespaced instance types
• kubevirt://{namespace}/preferences - Namespaced VM preferences
• kubevirt://cluster/instancetypes - Cluster-wide instance types
• kubevirt://cluster/preferences - Cluster-wide VM preferences
• kubevirt://cluster/instancetype/{name} - Specific cluster instance type
• kubevirt://cluster/preference/{name} - Specific cluster preference

Building

# Using Makefile (recommended)
make build

# Or directly with go
go build -o kubevirt-mcp-server .

Development

Available Make Targets

• make build - Build the binary (default)
• make clean - Clean build artifacts
• make test - Run tests with Ginkgo framework
• make coverage - Generate test coverage report
• make fmt - Format Go code
• make vet - Run go vet
• make lint - Run golangci-lint
• make deps - Download and tidy dependencies
• make run - Build and run the server
• make check - Run fmt, vet, lint, and test
• make cluster-up - Start kubevirtci cluster for testing
• make cluster-down - Stop kubevirtci cluster
• make cluster-sync - Build and run MCP server locally with kubevirtci access
• make test-functional - Run functional tests against MCP server
• make help - Show help message

Testing

The project uses the Ginkgo testing framework with Gomega assertions:

# Run unit tests
make test

# Generate test coverage report
make coverage

# Run functional tests against MCP server
make test-functional

# Run linter
make lint

# Run all quality checks
make check

Local Development Environment

For functional testing with a real KubeVirt cluster, use the kubevirtci integration:

# Start a local kubevirtci cluster with KubeVirt
make cluster-up

# Stop the cluster when done
make cluster-down

# Build and run MCP server locally with cluster access
make cluster-sync

The kubevirtci integration includes:

scripts/kubevirtci.sh handles:

• Downloading and setting up kubevirtci
• Starting a local Kubernetes cluster with KubeVirt and CDI
• Configuring the environment for testing
• Providing access to kubectl, kubeconfig, and registry

scripts/sync.sh handles:

• Building the MCP server binary
• Setting up proper KUBECONFIG environment for kubevirtci access
• Providing instructions for local MCP server execution

Test Structure

The project includes comprehensive test coverage:

• Unit Tests - Test individual components in isolation

  • pkg/client/client_test.go - KubeVirt client creation tests
  • pkg/tools/tools_test.go - MCP tool handler argument validation
  • pkg/resources/resources_test.go - MCP resource handler URI parsing

• Functional Tests - Test complete MCP server functionality

  • tests/functional/functional_suite_test.go - Test suite setup and KubeVirt cluster verification
  • tests/functional/mcp_server_stdio_test.go - Complete MCP server API coverage:
    • MCP server initialization and JSON-RPC communication
    • All MCP tools: list_vms, start_vm, stop_vm, restart_vm, create_vm, list_instancetypes, get_vm_instancetype, get_vm_disks
    • All MCP resources: kubevirt://namespace/vms, vm/name, vmis, vmi/name endpoints
    • Error handling for invalid tools, missing arguments, invalid URIs, and non-existent VMs

Using with Claude CLI

This MCP server integrates seamlessly with the Claude CLI (Claude Code) to provide KubeVirt management capabilities directly within your development workflow.

Configuration

Method 1: Project-Specific Configuration

Create a .clauderc file in your project directory:

{
  "mcp": {
    "servers": {
      "kubevirt": {
        "command": "/path/to/kubevirt-mcp-server",
        "env": {
          "KUBECONFIG": "/path/to/your/kubeconfig"
        }
      }
    }
  }
}

Method 2: Global Configuration

Configure in your global Claude settings:

# Create/edit global Claude config
mkdir -p ~/.config/claude
cat > ~/.config/claude/config.json << 'EOF'
{
  "mcp": {
    "servers": {
      "kubevirt": {
        "command": "/path/to/kubevirt-mcp-server",
        "env": {
          "KUBECONFIG": "/path/to/your/kubeconfig"
        }
      }
    }
  }
}
EOF

Method 3: Environment Variables

Set up environment variables for dynamic configuration:

export KUBEVIRT_MCP_SERVER="/path/to/kubevirt-mcp-server"
export KUBECONFIG="/path/to/your/kubeconfig"

# Use in Claude config
{
  "mcp": {
    "servers": {
      "kubevirt": {
        "command": "$KUBEVIRT_MCP_SERVER",
        "env": {
          "KUBECONFIG": "$KUBECONFIG"
        }
      }
    }
  }
}

Setup Steps

1. Build the MCP Server

   git clone <your-repo>
   cd kubevirt-mcp-server
   make build
   
   # Note the path to the binary
   echo "Binary location: $(pwd)/kubevirt-mcp-server"
   

2. Verify KubeVirt Access

   # Test your kubeconfig works
   kubectl get vms --all-namespaces
   
   # Test the MCP server directly
   export KUBECONFIG=/path/to/your/kubeconfig
   echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | ./kubevirt-mcp-server
   

3. Configure Claude CLI

   Use one of the configuration methods above, ensuring:

   • The command path points to your built binary
   • The KUBECONFIG environment variable points to your cluster config
   • The kubeconfig has appropriate permissions for VM operations

4. Test the Integration

   # Start Claude CLI and test MCP server connectivity
   claude --list-mcp-servers
   
   # Should show "kubevirt" server as available
   

Usage Examples

Once configured, you can use Claude CLI with natural language to manage your VMs:

VM Management

# List and manage VMs
claude "List all VMs in the production namespace"
claude "Start the web-server VM in default namespace"
claude "Restart all stopped VMs in the staging namespace"
claude "Show me the configuration of the database VM"

Troubleshooting

# VM diagnostics
claude "The payment-service VM isn't responding, can you investigate?"
claude "Compare the instance types of VMs in prod vs staging"
claude "What VMs are currently running and what resources are they using?"

Bulk Operations

# Mass management
claude "Stop all VMs in the test namespace"
claude "List all VMs that don't have instance types assigned"
claude "Show me a summary of VM status across all namespaces"

Development Workflow

# Development tasks
claude "Start my development VMs (web-dev, db-dev, cache-dev)"
claude "Check if my feature branch VMs are ready for testing"
claude "Clean up any VMs from old feature branches"

Available Capabilities

The MCP server provides Claude with these tools:

VM Lifecycle:

• list_vms - List VMs in a namespace
• start_vm - Start a specific VM
• stop_vm - Stop a specific VM
• restart_vm - Restart a VM
• pause_vm - Pause a VM
• unpause_vm - Unpause a VM
• create_vm - Create a new VM with container disk (supports OS names like "fedora", "ubuntu") and optional instancetype/preference
• delete_vm - Delete a VM
• patch_vm - Apply JSON merge patch to modify VM configuration

VM Information:

• get_vm_status - Get comprehensive VM status information
• get_vm_conditions - Get detailed VM condition information
• get_vm_phase - Get current VM phase and basic status
• get_vm_instancetype - Get VM's assigned instance type
• get_vm_disks - Retrieve the list of disks attached to a virtual machine

Instance Types & Preferences:

• list_instancetypes - List available instance types
• get_instancetype - Get detailed information about a specific instance type
• get_preference - Get detailed information about a specific preference

Prompts:

• describe_vm - Comprehensive VM description and analysis
• troubleshoot_vm - VM troubleshooting and diagnostics
• health_check_vm - Quick VM health checks

Container Disk Lookup: The create_vm tool supports both full container image URLs and OS name shortcuts:

• OS Names: "fedora", "ubuntu", "centos", "debian", "rhel", "opensuse", "alpine", "cirros", "windows", "freebsd"
• Full URLs: "quay.io/containerdisks/fedora:latest", "my-registry/my-image:tag"
• Auto-resolve: Unknown OS names are resolved to quay.io/containerdisks/{name}:latest

Structured Data:

• kubevirt://{namespace}/vms - VM summary data
• kubevirt://{namespace}/vm/{name} - Complete VM specs
• kubevirt://{namespace}/vmis - VM instance runtime data
• kubevirt://{namespace}/vmi/{name} - Complete VMI specs

Security Considerations

• Permissions: The MCP server uses your KUBECONFIG credentials
• Scope: Claude has the same KubeVirt permissions as your kubeconfig
• Best Practice: Consider using a dedicated service account with limited permissions:

# Create a dedicated service account for MCP operations
kubectl create serviceaccount kubevirt-mcp-user
kubectl create clusterrole kubevirt-mcp-role \
  --verb=get,list,create,update,patch,delete \
  --resource=virtualmachines,virtualmachineinstances
kubectl create clusterrolebinding kubevirt-mcp-binding \
  --clusterrole=kubevirt-mcp-role \
  --serviceaccount=default:kubevirt-mcp-user

# Generate kubeconfig for the service account
kubectl create token kubevirt-mcp-user > /path/to/mcp-kubeconfig

Troubleshooting

Connection Issues:

# Test MCP server manually
export KUBECONFIG=/path/to/your/kubeconfig
echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | ./kubevirt-mcp-server

Permission Issues:

# Verify kubeconfig access
kubectl auth can-i get virtualmachines
kubectl auth can-i create virtualmachines

Claude CLI Debug:

# Enable verbose logging
claude --verbose "List my VMs"

# Check MCP server logs
CLAUDE_MCP_DEBUG=1 claude "List VMs in default namespace"

Advanced Usage

Project-Specific VM Management:

# Create a .clauderc for your project
cat > .clauderc << 'EOF'
{
  "mcp": {
    "servers": {
      "kubevirt": {
        "command": "/usr/local/bin/kubevirt-mcp-server",
        "env": {
          "KUBECONFIG": "./k8s/kubeconfig",
          "DEFAULT_NAMESPACE": "myproject-dev"
        }
      }
    }
  },
  "context": {
    "project": "MyProject Development VMs",
    "defaultNamespace": "myproject-dev"
  }
}
EOF

# Now Claude understands your project context
claude "Start my development environment"
claude "Show me the status of project VMs"

Demo

This short demo uses mcp-cli as a bridge between the kubevirt-mcp-server and LLM.

The model used by the demo is llama3.2 running locally under ollama.

Links

• https://www.anthropic.com/news/model-context-protocol
• https://github.com/mark3labs/mcp-go
• https://github.com/chrishayuk/mcp-cli