Kubevirt MCP Server

kubevirt-mcp服务器

KubeVirt的简单模型上下文协议服务器。

建筑

该项目分为模块化包：

• main.go -MCP服务器设置和注册
• pkg/client/ -共享KubeVirt客户端实用程序
• pkg/tools/ -用于VM操作的MCP工具处理程序
• pkg/resources/ -用于结构化数据访问的MCP资源处理程序
• scripts/kubevirtci.sh -用于管理本地kubevirtci开发环境的脚本
• scripts/sync.sh -使用kubevirtci访问在本地构建和运行MCP服务器的脚本
• Makefile -构建自动化和开发任务

特性

MCP工具

• list_vms -列出命名空间中的虚拟机名称
• start_vm -启动虚拟机
• stop_vm -停止虚拟机
• restart_vm -重新启动虚拟机（处理正在运行和已停止的VM）
• pause_vm -暂停虚拟机
• unpause_vm -取消虚拟机的暂停
• create_vm -使用指定的容器磁盘（支持操作系统名称查找）、可选的实例类型和首选项创建虚拟机
• delete_vm -删除虚拟机
• patch_vm -应用JSON合并补丁修改VM配置
• list_instancetypes -列出可用的实例类型
• get_instancetype -获取特定实例类型的详细信息
• get_preference -获取特定偏好的详细信息
• get_vm_instancetype -获取VM的实例类型
• get_vm_status -获取全面的VM状态信息
• get_vm_conditions -获取详细的VM状态信息
• get_vm_phase -获取当前VM阶段和基本状态
• get_vm_disks -检索连接到虚拟机的磁盘列表

MCP提示

• describe_vm -提供全面的VM描述，包括配置、状态和操作细节
• troubleshoot_vm -诊断和分析潜在的VM问题，并提出可操作的建议
• health_check_vm -执行快速VM健康检查并报告问题

MCP资源

• kubevirt://{namespace}/vms -带有摘要信息的虚拟机JSON列表
• kubevirt://{namespace}/vm/{name} -完整的VM规范
• kubevirt://{namespace}/vm/{name}/status -VM状态和阶段信息
• kubevirt://{namespace}/vm/{name}/console -VM控制台连接详细信息
• kubevirt://{namespace}/vmis -带有运行时信息的VMI JSON列表
• kubevirt://{namespace}/vmi/{name} -完整的VMI规范
• kubevirt://{namespace}/vmi/{name}/guestosinfo -VMI客户操作系统信息
• kubevirt://{namespace}/vmi/{name}/filesystems -VMI文件系统信息
• kubevirt://{namespace}/vmi/{name}/userlist -VMI用户列表信息
• kubevirt://{namespace}/datavolumes -包含源和存储信息的DataVolume JSON列表
• kubevirt://{namespace}/datavolume/{name} -完整的数据量规格
• kubevirt://{namespace}/instancetypes -命名空间实例类型
• kubevirt://{namespace}/preferences -命名空间VM首选项
• kubevirt://cluster/instancetypes -集群范围内的实例类型
• kubevirt://cluster/preferences -群集范围内的VM首选项
• kubevirt://cluster/instancetype/{name} -特定集群实例类型
• kubevirt://cluster/preference/{name} -特定集群偏好

建筑

# Using Makefile (recommended)
make build

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

发展

可用生成目标

• make build -构建二进制文件（默认）
• make clean -清理构建工件
• make test -使用Ginkgo框架运行测试
• make coverage -生成测试覆盖率报告
• make fmt -设置Go代码格式
• make vet -快跑兽医
• make lint -运行golangci lint
• make deps -下载并整理依赖关系
• make run -构建并运行服务器
• make check -运行fmt、兽医、皮棉和测试
• make cluster-up -启动kubevirtci集群进行测试
• make cluster-down -停止kubevirtci集群
• make cluster-sync -使用kubevirtci访问在本地构建和运行MCP服务器
• make test-functional -对MCP服务器运行功能测试
• make help -显示帮助消息

测试

# 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

当地发展环境

要使用真实的KubeVirt集群进行功能测试，请使用kubevirtci集成：

# 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

kubevirtci集成包括：

scripts/kubevirtci.sh 手柄：

• 下载并设置kubevirtci
• 使用KubeVirt和CDI启动本地Kubernetes集群
• 配置测试环境
• 提供对kubectl、kubeconfig和注册表的访问

scripts/sync.sh 手柄：

• 构建MCP服务器二进制文件
• 为kubevirtci访问设置适当的KUBECONFIG环境
• 提供本地MCP服务器执行说明

测试结构

该项目包括全面的测试覆盖范围：

• 单元测试 -单独测试单个组件

- pkg/client/client_test.go -KubeVirt客户端创建测试 - pkg/tools/tools_test.go -MCP工具处理程序参数验证 - pkg/resources/resources_test.go -MCP资源处理程序URI解析

• 功能测试 -测试完整的MCP服务器功能

- tests/functional/functional_suite_test.go -测试套件设置和KubeVirt集群验证 - tests/functional/mcp_server_stdio_test.go -完整的MCP服务器API覆盖范围： - MCP服务器初始化和JSON-RPC通信 - 所有MCP工具：list_vms、start_vm、stop_vm、restart_vm、create_vm、list_instancetypes、get_vm_instancetype、get_vm_disks - 所有MCP资源：kubevirt://namespace/vms、vm/name、vmis、vmi/name端点 - 对无效工具、缺少参数、无效URI和不存在的VM的错误处理

使用Claude CLI

此MCP服务器与Claude CLI（Claude Code）无缝集成，直接在您的开发工作流程中提供KubeVirt管理功能。

配置

方法1：项目特定配置

创建一个 .clauderc 项目目录中的文件：

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

方法2：全局配置

在全局Claude设置中配置：

# Create/edit global Claude config
mkdir -p ~/.config/claude
cat > ~/.config/claude/config.json 
   cd kubevirt-mcp-server
   make build

   # Note the path to the binary
   echo "Binary location: $(pwd)/kubevirt-mcp-server"

1. 验证KubeVirt访问权限

   # 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

1. 配置Claude CLI

使用上述配置方法之一，确保：

- 这 command 路径指向您构建的二进制文件 - 这 KUBECONFIG 环境变量指向集群配置 - kubeconfig具有VM操作的适当权限

1. 测试集成

   # Start Claude CLI and test MCP server connectivity
   claude --list-mcp-servers

   # Should show "kubevirt" server as available

使用示例

配置后，您可以使用带有自然语言的Claude CLI来管理您的虚拟机：

虚拟机管理

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

故障排除

# 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?"

批量操作

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

可用功能

MCP服务器为Claude提供了以下工具：

VM生命周期：

• list_vms -在命名空间中列出虚拟机
• start_vm -启动特定VM
• stop_vm -停止特定VM
• restart_vm -重新启动虚拟机
• pause_vm -暂停虚拟机
• unpause_vm -取消VM的暂停
• create_vm -使用容器磁盘（支持“fedora”、“ubuntu”等操作系统名称）和可选的实例类型/首选项创建新的VM
• delete_vm -删除虚拟机
• patch_vm -应用JSON合并补丁修改VM配置

VM信息：

• get_vm_status -获取全面的VM状态信息
• get_vm_conditions -获取详细的VM状态信息
• get_vm_phase -获取当前VM阶段和基本状态
• get_vm_instancetype -获取VM分配的实例类型
• get_vm_disks -检索连接到虚拟机的磁盘列表

实例类型和首选项：

• list_instancetypes -列出可用的实例类型
• get_instancetype -获取特定实例类型的详细信息
• get_preference -获取特定偏好的详细信息

提示：

• describe_vm -全面的VM描述和分析
• troubleshoot_vm -VM故障排除和诊断
• health_check_vm -快速VM健康检查

容器磁盘查找： 这 create_vm 该工具支持全容器映像URL和操作系统名称快捷方式：

• 操作系统名称: "fedora", "ubuntu", "centos", "debian", "rhel", "opensuse", "alpine", "cirros", "windows", "freebsd"
• 完整URL: "quay.io/containerdisks/fedora:latest", "my-registry/my-image:tag"
• 自动解析：未知的操作系统名称被解析为 quay.io/containerdisks/{name}:latest

结构化数据：

• kubevirt://{namespace}/vms -VM摘要数据
• kubevirt://{namespace}/vm/{name} -完整的VM规格
• kubevirt://{namespace}/vmis -VM实例运行时数据
• kubevirt://{namespace}/vmi/{name} -完整的VMI规格

安全考虑

• 权限：MCP服务器使用您的KUBECONFIG凭据
• 范围：Claude拥有与kubeconfig相同的KubeVirt权限
• 最佳实践：考虑使用权限有限的专用服务帐户：

# 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

故障排除

连接问题：

# 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

权限问题：

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

Claude CLI调试：

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

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

高级用法

项目特定VM管理：

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

演示

这个简短的演示使用mcp-cli作为kubevirt-mcp服务器和LLM之间的桥梁。

演示使用的模型是llama3.2，在ollama下本地运行。

demo

链接

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