start_vm
Power on a stopped or suspended virtual machine managed by UTM via MCP.
Instructions
Start a stopped or suspended VM.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Implementation Reference
- src/mcp_utm/applescript.py:249-259 (handler)Core handler: executes AppleScript to start a UTM VM via osascript and returns the status string.
def start_vm(name: str) -> str: """Start a VM. Returns status after start command.""" _validate_vm_name(name) script = f''' tell application "UTM" set vm to virtual machine named "{_esc(name)}" start vm return status of vm as text end tell ''' return _run(script, timeout=60) - src/mcp_utm/server.py:48-52 (handler)MCP tool handler: decorated with @mcp.tool(), delegates to applescript.start_vm() and wraps the result in a dict.
@mcp.tool() def start_vm(name: str) -> dict: """Start a stopped or suspended VM.""" status = utm.start_vm(name) return {"name": name, "status": status} - src/mcp_utm/server.py:48-48 (registration)Registration of 'start_vm' as an MCP tool via the @mcp.tool() decorator on FastMCP instance.
@mcp.tool() - src/mcp_utm/applescript.py:33-36 (helper)Input validation helper: ensures VM name only contains safe characters before AppleScript interpolation.
def _validate_vm_name(name: str) -> str: if not name or not _VM_NAME_RE.match(name): raise ValueError(f"Invalid VM name: {name!r} — only word characters, spaces, hyphens, and dots allowed") return name - src/mcp_utm/applescript.py:61-74 (helper)Helper: executes AppleScript via subprocess (osascript), with timeout and error handling.
def _run(script: str, timeout: int = 30) -> str: """Execute an AppleScript snippet and return stdout.""" result = subprocess.run( ["osascript", "-e", script], capture_output=True, text=True, timeout=timeout, ) if result.returncode != 0: err = result.stderr.strip() if "Application can" in err and "found" in err: raise RuntimeError("UTM is not running. Launch UTM and try again.") raise RuntimeError(err or f"osascript failed (rc={result.returncode})") return result.stdout.strip()