{"id":"c631a270-cdbe-46ce-b7db-a0161f8d1a8c","slug":"utm-mcp","kind":"mcp","name":"utm-mcp","summary":"","owner":"michaelbarry","repoUrl":"https://github.com/michaelbarry/utm_mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-02-15T12:15:17.000Z","addedAt":"2026-10-21T16:51:55.424Z","logoUrl":"https://avatars.githubusercontent.com/u/6878403?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T08:39:10.954Z","sample":false,"url":"https://conduits.dev/tools/utm-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"utm-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# UTM MCP Server\n\nAn MCP (Model Context Protocol) server that provides tools for managing [UTM](https://mac.getutm.app/) virtual machines via the `utmctl` CLI.\n\n## Prerequisites\n\n- macOS with [UTM](https://mac.getutm.app/) installed at `/Applications/UTM.app`\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/getting-started/installation/)\n- UTM must be running in the current user session (`utmctl` uses Apple Events)\n\n## Setup\n\n```bash\ngit clone https://github.com/michaelbarry/utm_mcp.git\ncd utm_mcp\nuv sync\n```\n\n## Running\n\n```bash\nuv run utm-mcp\n```\n\nThe server uses stdio transport by default, suitable for use with Claude Code and other MCP clients.\n\n## Claude Desktop Configuration\n\nRun the helper script to automatically add the server to your Claude Desktop config:\n\n```bash\nuv run python add_to_claude_desktop.py\n\n# Or specify the path to your utm_mcp checkout\nuv run python add_to_claude_desktop.py /path/to/utm_mcp\n```\n\nOr manually add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"utm\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/utm_mcp\", \"run\", \"utm-mcp\"]\n    }\n  }\n}\n```\n\n## Claude Code Configuration\n\n```bash\nclaude mcp add -s user utm -- uv --directory /path/to/utm_mcp run utm-mcp\n```\n\n## Tools\n\n### VM Lifecycle\n\n| Tool | Description |\n|------|-------------|\n| `utm_list_vms` | List all registered virtual machines |\n| `utm_get_status` | Query the status of a VM |\n| `utm_start_vm` | Start or resume a VM (supports disposable and recovery mode) |\n| `utm_suspend_vm` | Suspend a running VM to memory (optionally save state to disk) |\n| `utm_stop_vm` | Shut down a VM (force, kill, or graceful request) |\n| `utm_clone_vm` | Clone an existing VM (with disk space checks and warnings) |\n| `utm_delete_vm` | Permanently delete a VM (irreversible) |\n| `utm_get_ip_address` | List IP addresses on the guest |\n\n### Guest Operations\n\nRequire the QEMU guest agent running inside the VM. See [Installing the QEMU Guest Agent](#installing-the-qemu-guest-agent) below.\n\n| Tool | Description |\n|------|-------------|\n| `utm_exec_command` | Execute a command inside the guest |\n| `utm_exec_script` | Push and execute a multi-line script on the guest |\n| `utm_file_pull` | Fetch a file from the guest |\n| `utm_file_push` | Upload text content to a file on the guest |\n\n### USB\n\n| Tool | Description |\n|------|-------------|\n| `utm_list_usb` | List connected USB devices |\n| `utm_connect_usb` | Connect a USB device to a VM |\n| `utm_disconnect_usb` | Disconnect a USB device from a VM |\n\n## Installing the QEMU Guest Agent\n\nThe 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:\n\n### Linux\n\n**Debian / Ubuntu:**\n```bash\nsudo apt update && sudo apt install -y qemu-guest-agent\nsudo systemctl enable --now qemu-guest-agent\n```\n\n**Fedora / RHEL / CentOS:**\n```bash\nsudo dnf install -y qemu-guest-agent\nsudo systemctl enable --now qemu-guest-agent\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S qemu-guest-agent\nsudo systemctl enable --now qemu-guest-agent\n```\n\n**Alpine Linux:**\n```bash\nsudo apk add qemu-guest-agent\nsudo rc-update add qemu-guest-agent\nsudo service qemu-guest-agent start\n```\n\n**NixOS:**\n\nAdd to `configuration.nix`:\n```nix\nservices.qemuGuest.enable = true;\n```\nThen rebuild:\n```bash\nsudo nixos-rebuild switch\n```\n\n### Windows\n\n1. Download the [VirtIO guest tools ISO](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso)\n2. Mount the ISO in UTM (CD/DVD drive)\n3. Run `guest-agent\\qemu-ga-x86_64.msi` (or `qemu-ga-i386.msi` for 32-bit) from the mounted drive\n4. The agent starts automatically as a Windows service\n\n### Verifying the Agent\n\nAfter installing, verify the agent is running by checking the VM status from the host:\n\n```bash\n/Applications/UTM.app/Contents/MacOS/utmctl exec <vm-name> -- echo \"agent works\"\n```\n\nIf this returns `agent works`, guest operations are ready to use.\n\n## Storage Notes\n\n`utm_clone_vm` checks available disk space before cloning and warns if:\n\n- UTM storage is on the local disk rather than external storage\n- Free space would drop below 50 GB after the clone\n\nUTM can be configured to store VMs on an external volume via UTM preferences. This is recommended for machines with limited internal storage.\n\n## Troubleshooting\n\n### `utmctl` returns no VMs (OSStatus error -1743)\n\n`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.\n\n**Fix:**\n\n1. Run this command in your terminal to trigger the macOS permission prompt:\n\n   ```bash\n   osascript -e 'tell application \"UTM\" to get name of every virtual machine'\n   ```\n\n2. Approve the dialog that appears, granting your terminal app permission to control UTM.\n3. You can verify or manage this permission in **System Settings → Privacy & Security → Automation**.\n\n> **Note:** If you're using the App Store (sandboxed) version of UTM and continue to have issues, the [direct download](https://mac.getutm.app/) is known to work more reliably with `utmctl`.\n\n## Limitations\n\n- `utmctl` requires an active GUI session (Apple Events). It does not work over SSH.\n- Guest operations require the QEMU/SPICE guest agent installed and running inside the VM.\n- Clone operations copy the entire VM disk image and can take significant time and space.\n\n## License\n\nMIT\n"}