mcp-utm
MCP server for managing UTM virtual machines on macOS via AppleScript.
Provides 22 tools for cloning, configuring, and controlling UTM VMs — including proper MAC address randomization for Apple Virtualization Framework clones, which enables concurrent VMs with unique network identities.
Install
# PyPI
uvx mcp-utm
# Or install globally
uv tool install mcp-utm
pip install mcp-utm
Claude Code config
{
"mcpServers": {
"utm": {
"command": "uvx",
"args": ["mcp-utm"]
}
}
}
Requirements
- macOS (uses AppleScript /
osascript) - UTM 4.6+ (download or
brew install --cask utm) - Python 3.11+
Tools
Lifecycle
| Tool | Description |
|---|---|
list_vms | List all registered VMs with status |
get_vm | Get status and configuration of a VM |
clone_vm | Clone a template with unique random MAC |
start_vm | Start a stopped or suspended VM |
stop_vm | Stop a running VM (graceful or force) |
delete_vm | Delete a VM permanently |
State
| Tool | Description |
|---|---|
suspend_vm | Suspend a running VM to memory |
wait_for_vm | Poll until VM reaches a target status |
Networking
| Tool | Description |
|---|---|
get_vm_ip | Discover VM IP via ARP table |
set_vm_network | Update MAC address or network mode |
Configuration
| Tool | Description |
|---|---|
set_vm_resources | Update memory and CPU cores |
rename_vm | Rename a VM |
set_vm_display | Toggle dynamic resolution |
Directory Shares (VirtioFS)
| Tool | Description |
|---|---|
list_vm_shares | List shared directories |
add_vm_share | Add a host directory share |
remove_vm_share | Remove a directory share |
set_vm_shares | Replace all shares |
Drives
| Tool | Description |
|---|---|
list_vm_drives | List attached drives |
attach_drive | Attach an ISO or disk image |
Portability
| Tool | Description |
|---|---|
export_vm | Export VM to a .utm file |
import_vm | Import VM from a .utm file |
Console
| Tool | Description |
|---|---|
get_serial_port | Get serial port address for console access |
How MAC randomization works
Apple's Virtualization Framework ignores MacAddress changes written directly to config.plist — UTM caches the config in memory. This server uses AppleScript's update configuration command which properly updates UTM's internal state, giving each clone a unique MAC and therefore a unique IP on the 192.168.64.0/24 subnet.
License
MIT