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