utm-mcp

UTM MCP Server

An MCP (Model Context Protocol) server that provides tools for managing UTM virtual machines via the utmctl CLI.

Prerequisites

• macOS with UTM installed at /Applications/UTM.app
• Python 3.10+
• uv
• UTM must be running in the current user session (utmctl uses Apple Events)

Setup

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

Running

uv run utm-mcp

The server uses stdio transport by default, suitable for use with Claude Code and other MCP clients.

Claude Desktop Configuration

Run the helper script to automatically add the server to your Claude Desktop config:

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

Or manually add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Claude Code Configuration

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

Tools

VM Lifecycle

Tool	Description
utm_list_vms	List all registered virtual machines
utm_get_status	Query the status of a VM
utm_start_vm	Start or resume a VM (supports disposable and recovery mode)
utm_suspend_vm	Suspend a running VM to memory (optionally save state to disk)
utm_stop_vm	Shut down a VM (force, kill, or graceful request)
utm_clone_vm	Clone an existing VM (with disk space checks and warnings)
utm_delete_vm	Permanently delete a VM (irreversible)
utm_get_ip_address	List IP addresses on the guest

Guest Operations

Require the QEMU guest agent running inside the VM. See Installing the QEMU Guest Agent below.

Tool	Description
utm_exec_command	Execute a command inside the guest
utm_exec_script	Push and execute a multi-line script on the guest
utm_file_pull	Fetch a file from the guest
utm_file_push	Upload text content to a file on the guest

USB

Tool	Description
utm_list_usb	List connected USB devices
utm_connect_usb	Connect a USB device to a VM
utm_disconnect_usb	Disconnect a USB device from a VM

Installing the QEMU Guest Agent

The guest agent is required for guest operations (utm_exec_command, utm_exec_script, utm_file_pull, utm_file_push). Install it inside each VM you want to manage:

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:

Add to configuration.nix:

services.qemuGuest.enable = true;

Then rebuild:

sudo nixos-rebuild switch

Windows

1. Download the VirtIO guest tools ISO
2. Mount the ISO in UTM (CD/DVD drive)
3. Run guest-agent\qemu-ga-x86_64.msi (or qemu-ga-i386.msi for 32-bit) from the mounted drive
4. The agent starts automatically as a Windows service

Verifying the Agent

After installing, verify the agent is running by checking the VM status from the host:

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

If this returns agent works, guest operations are ready to use.

Storage Notes

utm_clone_vm checks available disk space before cloning and warns if:

• UTM storage is on the local disk rather than external storage
• Free space would drop below 50 GB after the clone

UTM can be configured to store VMs on an external volume via UTM preferences. This is recommended for machines with limited internal storage.

Troubleshooting

utmctl returns no VMs (OSStatus error -1743)

utmctl communicates with UTM.app via Apple Events. If the app running utmctl (Terminal, iTerm, VS Code, etc.) hasn't been granted Automation permission, macOS silently blocks the request and no VMs are returned.

Fix:

1. Run this command in your terminal to trigger the macOS permission prompt:

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

2. Approve the dialog that appears, granting your terminal app permission to control UTM.

3. You can verify or manage this permission in System Settings → Privacy & Security → Automation.

Note: If you're using the App Store (sandboxed) version of UTM and continue to have issues, the direct download is known to work more reliably with utmctl.

Limitations

• utmctl requires an active GUI session (Apple Events). It does not work over SSH.
• Guest operations require the QEMU/SPICE guest agent installed and running inside the VM.
• Clone operations copy the entire VM disk image and can take significant time and space.

License

MIT