AI agents (MCP)

elyravm mcp is a Model Context Protocol server: an agent that speaks MCP (Claude Code, Claude Desktop, and others) can run your VMs and work in them. It runs on your Mac, speaks on its standard input and output, and reaches each VM as the command line does, so a guest needs nothing more than Elyra VM Tools.

Adding it

Claude Code:

claude mcp add elyravm -- "/Applications/Elyra VM.app/Contents/MacOS/Elyra VM" mcp

Any other client, in its configuration (Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "elyravm": {
      "command": "/Applications/Elyra VM.app/Contents/MacOS/Elyra VM",
      "args": ["mcp"]
    }
  }
}

Tools

Tool	What it does
`list_vms`	The VMs, with their state, system, size and address
`vm_status`	A VM's state, whether Elyra VM Tools runs in it, its address, ports and USB disks
`vm_control`	Start (without its window, unless asked), stop, force-stop, pause, resume, suspend, show
`exec`	Runs a command in a VM and waits: its exit status, output and errors
`copy`	Copies a file or folder between the Mac and a VM (`<vm>:<path>` on one side)
`send_files`	Sends files into a VM's Downloads, as dropping them on its window does
`list_snapshots`, `snapshot`	A VM's snapshots; take, restore or delete one
`forward_port`	Forwards a Mac port to a VM's, stops it, or lists them
`usb_disk`	Plugs a disk image into a running VM as a USB disk, or pulls it out
`screenshot`	What a running VM's screen shows, as an image the agent sees
`type_text`, `press_keys`	Types text (as on a US keyboard), or presses keys together (`ctrl+alt+delete`, `win+r`, `cmd+space`)
`click`, `move_pointer`, `scroll`	Points at places in the screenshot's pixels

A VM is named by its name or the start of its id. exec, copy and send_files need Elyra VM Tools in the guest (see Elyra VM Tools); vm_status says when it runs (tools).

With screenshot and the keyboard and pointer, an agent works at a VM's screen as a person would: in a Windows VM from its first start (its setup too, before Elyra VM Tools is in it); in a Linux VM with Elyra VM's own GPU (3D graphics, with Elyra VM Tools); in a macOS VM, where the screenshot is taken in the guest, once a user is logged in with Elyra VM Tools. A Linux VM shown through Apple's display view takes the keyboard and pointer, but its screen can't be read.

Each tool runs the command line with --json: what an agent can do through MCP is what you can do in a terminal, no more. An agent you let use it can do anything in your VMs that you can, as root in Linux and macOS guests and as the system in Windows unless it asks for a user: give it to agents you trust with them.