rename_vm
Rename a stopped virtual machine managed by UTM on macOS by specifying the current name and the new name.
Instructions
Rename a stopped VM.
Args: name: Current VM name (must be stopped) new_name: New name for the VM
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| new_name | Yes |
Implementation Reference
- src/mcp_utm/server.py:135-144 (registration)The MCP tool registration for 'rename_vm' using the @mcp.tool() decorator. It delegates to utm.rename_vm() and returns the config as a dict.
@mcp.tool() def rename_vm(name: str, new_name: str) -> dict: """Rename a stopped VM. Args: name: Current VM name (must be stopped) new_name: New name for the VM """ config = utm.rename_vm(name, new_name) return config.to_dict() - src/mcp_utm/applescript.py:310-323 (handler)The core implementation of rename_vm. Validates both old and new names, constructs an AppleScript that updates the VM configuration's name, executes via osascript, then retrieves and returns the updated VM config.
def rename_vm(name: str, new_name: str) -> VMConfig: """Rename a stopped VM via update configuration.""" _validate_vm_name(name) _validate_vm_name(new_name) script = f''' tell application "UTM" set vm to virtual machine named "{_esc(name)}" set conf to configuration of vm set name of conf to "{_esc(new_name)}" update configuration of vm with conf end tell ''' _run(script) return get_vm_config(new_name) - src/mcp_utm/applescript.py:28-30 (helper)The _esc helper escapes backslashes and double-quotes for safe AppleScript string interpolation.
def _esc(value: str) -> str: """Escape a string for safe interpolation into AppleScript double-quoted literals.""" return value.replace("\\", "\\\\").replace('"', '\\"') - src/mcp_utm/applescript.py:33-36 (helper)The _validate_vm_name helper used by rename_vm to check both old and new names against the allowed character pattern.
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)The _run helper that executes AppleScript snippets via subprocess (osascript), used by rename_vm to apply the name change.
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()