UTM MCP服务器
提供管理工具的MCP（模型上下文协议）服务器 统一威胁管理 虚拟机通过 utmctl CLI。
先决条件
设置
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-agentFedora/RHEL/CentOS：
sudo dnf install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agentArch Linux：
sudo pacman -S qemu-guest-agent
sudo systemctl enable --now qemu-guest-agentAlpine Linux：
sudo apk add qemu-guest-agent
sudo rc-update add qemu-guest-agent
sudo service qemu-guest-agent startNixOS ：
添加 configuration.nix:
services.qemuGuest.enable = true;然后重建：
sudo nixos-rebuild switch视窗
- 下载 VirtIO客户工具ISO
- 在UTM（CD/DVD驱动器）中安装ISO
- 跑
guest-agent\qemu-ga-x86_64.msi（或qemu-ga-i386.msi对于32位）从已安装的驱动器 - 代理作为Windows服务自动启动
验证代理
安装后，通过检查主机上的VM状态来验证代理是否正在运行：
/Applications/UTM.app/Contents/MacOS/utmctl exec -- 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。
修复：
- 在终端中运行此命令以触发macOS权限提示：
osascript -e 'tell application "UTM" to get name of every virtual machine'- 批准出现的对话框，授予您的终端应用程序控制UTM的权限。
- 您可以在中验证或管理此权限 系统设置→ 隐私和安全→ 自动化.
注： 如果您使用的是UTM的App Store（沙盒）版本，并且仍然存在问题 直接下载 已知与以下设备配合使用更可靠 utmctl.局限性
utmctl需要活动的GUI会话（Apple Events）。它不适用于SSH。- 来宾操作需要在VM内安装并运行QEMU/SPICE来宾代理。
- 克隆操作会复制整个VM磁盘映像，可能会占用大量时间和空间。
许可证
麻省理工学院