AI导哈

虚拟机管理服务器

UTM MCP Server是一个用于通过utmctl CLI管理UTM虚拟机的工具，提供虚拟机生命周期管理、客户机操作和USB设备管理功能。

  • by michaelbarry
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 michaelbarry/utm_mcp

使用说明

UTM MCP服务器

提供管理工具的MCP（模型上下文协议）服务器 统一威胁管理 虚拟机通过 utmctl CLI。

先决条件

  • macOS与 统一威胁管理 安装在 /Applications/UTM.app
  • Python 3.10+
  • 紫外线
  • UTM必须在当前用户会话中运行(utmctl 使用Apple活动）

设置

git clone https://github.com/michaelbarry/utm_mcp.git
cd utm_mcp
uv sync

跑步

uv run utm-mcp

服务器默认使用stdio传输，适用于Claude Code和其他MCP客户端。

Claude桌面配置

运行辅助脚本，将服务器自动添加到您的Claude Desktop配置中：

uv run python add_to_claude_desktop.py

# Or specify the path to your utm_mcp checkout
uv run python add_to_claude_desktop.py /path/to/utm_mcp

或手动添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "utm": {
      "command": "uv",
      "args": ["--directory", "/path/to/utm_mcp", "run", "utm-mcp"]
    }
  }
}

Claude代码配置

claude mcp add -s user utm -- uv --directory /path/to/utm_mcp run utm-mcp

工具

VM生命周期

工具 说明
utm_list_vms 列出所有已注册的虚拟机
utm_get_status 查询虚拟机的状态
utm_start_vm 启动或恢复虚拟机（支持一次性和恢复模式）
utm_suspend_vm 将正在运行的VM挂起到内存中（可选地将状态保存到磁盘）
utm_stop_vm 关闭虚拟机（强制、终止或优雅请求）
utm_clone_vm 克隆现有VM（带有磁盘空间检查和警告）
utm_delete_vm 永久删除虚拟机（不可逆）
utm_get_ip_address 列出来宾的IP地址

客户操作

要求QEMU来宾代理在VM内运行。看 安装QEMU来宾代理 在......下面

工具 说明
utm_exec_command 在来宾内部执行命令
utm_exec_script 在来宾上推送并执行多行脚本
utm_file_pull 从访客处获取文件
utm_file_push 将文本内容上传到来宾的文件中

通用串行总线

工具 说明
utm_list_usb 列出已连接的USB设备
utm_connect_usb 将USB设备连接到VM
utm_disconnect_usb 断开USB设备与VM的连接

安装QEMU来宾代理

客人操作需要客人代理(utm_exec_command, utm_exec_script, utm_file_pull, utm_file_push).安装它 里面 您要管理的每个VM：

Linux

Debian/Ubuntu：

sudo apt update && sudo apt install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

Fedora/RHEL/CentOS：

sudo dnf install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

Arch Linux：

sudo pacman -S qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

Alpine Linux：

sudo apk add qemu-guest-agent
sudo rc-update add qemu-guest-agent
sudo service qemu-guest-agent start

NixOS ：

添加 configuration.nix:

services.qemuGuest.enable = true;

然后重建：

sudo nixos-rebuild switch

视窗

  1. 下载 VirtIO客户工具ISO
  2. 在UTM（CD/DVD驱动器）中安装ISO
  3. 跑 guest-agent\qemu-ga-x86_64.msi （或 qemu-ga-i386.msi 对于32位）从已安装的驱动器
  4. 代理作为Windows服务自动启动

验证代理

安装后，通过检查主机上的VM状态来验证代理是否正在运行：

/Applications/UTM.app/Contents/MacOS/utmctl exec <vm-name> -- echo "agent works"

如果返回 agent works，客户操作已准备就绪。

存储注意事项

utm_clone_vm 在克隆之前检查可用磁盘空间，并在以下情况下发出警告：

  • UTM存储在本地磁盘上，而不是外部存储
  • 克隆后可用空间将降至50 GB以下

UTM可以配置为通过UTM首选项将VM存储在外部卷上。建议用于内部存储空间有限的机器。

故障排除

utmctl 不返回虚拟机（OSStatus错误-1743）

utmctl 通过Apple Events与UTM.app通信。如果应用程序正在运行 utmctl （终端、iTerm、VS代码等）未被授予自动化权限，macOS会自动阻止请求，并且不会返回任何VM。

修复：

  1. 在终端中运行此命令以触发macOS权限提示：

    osascript -e 'tell application "UTM" to get name of every virtual machine'

  2. 批准出现的对话框，授予您的终端应用程序控制UTM的权限。

  3. 您可以在中验证或管理此权限 系统设置→ 隐私和安全→ 自动化.

注： 如果您使用的是UTM的App Store（沙盒）版本，并且仍然存在问题 直接下载 已知与以下设备配合使用更可靠 utmctl.

局限性

  • utmctl 需要活动的GUI会话（Apple Events）。它不适用于SSH。
  • 来宾操作需要在VM内安装并运行QEMU/SPICE来宾代理。
  • 克隆操作会复制整个VM磁盘映像，可能会占用大量时间和空间。

许可证

麻省理工学院

相关 MCP