skills / qemu-mcp.md
qemu-mcp is a set of 3 tools that let you control a QEMU virtual machine (VM) through its serial console and the QEMU Machine Protocol (QMP). Think of it as remote control for a computer that runs inside QEMU:
execute_qmp — send commands to QEMU itself (check status, stop, restart, eject a CD).read_serial — read what the guest VM is printing to its serial console (like reading a screen).write_serial — type into the guest VM's serial console (like typing on a keyboard).skills / qemu-mcp.md
qemu-mcp is a set of 3 tools that let you control a QEMU virtual machine (VM) through its serial console and the QEMU Machine Protocol (QMP). Think of it as remote control for a computer that runs inside QEMU:
execute_qmp — send commands to QEMU itself (check status, stop, restart, eject a CD).read_serial — read what the guest VM is printing to its serial console (like reading a screen).write_serial — type into the guest VM's serial console (like typing on a keyboard).These tools are useful when you want to plan, manage, monitor, and summarize VM tasks without leaving your chat.
| Tool | What it does | Key parameters |
|---|---|---|
execute_qmp | Runs a QMP command on the QEMU instance | qmp_command (string), qmp_arguments (JSON string) |
read_serial | Reads buffered output from the guest serial console | wait_for (optional), timeout_ms (default 5000), max_chars (optional), clear (default false) |
write_serial | Writes text to the guest serial console (simulates typing) | data (string), newline (default true) |
execute_qmp with query-status to see if the VM
is running, paused, or stopped.wait_for with read_serial when you expect a specific prompt (e.g. a login prompt or a boot
message). This makes the tool wait until that text appears.write_serial input small. Send one line or one short command at a time. Do not paste a huge
script in one call.newline to what the guest expects. Most prompts need a newline (leave newline: true).clear: true when you have read what you need and want to reset the serial buffer for a fresh
sequence of reads.-qmp and -serial flags.Goal: find out whether the VM is running.
{ "qmp_command": "query-status", "qmp_arguments": "{}" }
Goal: remove the CD image from the ide-cd0 drive.
{ "qmp_command": "eject", "qmp_arguments": "{\"device\": \"ide-cd0\"}" }
Goal: read the guest console and stop when you see a Login: prompt.
read_serial with wait_for: "Login:", timeout_ms: 30000.Login: prompt.-serial unix:/tmp/serial-sock,server,nowait.You want to install an operating system in the VM and drive it automatically.
Plan:
read_serial with wait_for to find the installer's first prompt (e.g. Press any key to boot...).write_serial to send the key (e.g. a newline or a letter) that advances the installer.read_serial to confirm the reboot message.execute_qmp with query-status to verify the VM is running after reboot.Tip: Keep a note of the exact prompt text you are waiting for. Small mismatches in wait_for will cause
timeouts.
You need to manage the VM's power state safely.
Plan:
execute_qmp → query-status to know the current state.execute_qmp → stop, then wait for the VM to halt using
read_serial or another query-status.execute_qmp → cont.You want to monitor the VM's resources and devices.
Plan:
execute_qmp with query-status for the basic running state.qmp_command) to query devices, memory, and CPU. For example,
query block devices to see which ISO is attached to which drive.| Problem | What to check |
|---|---|
| Tool returns an error about a socket | Make sure QEMU is running with -qmp unix:/tmp/qmp-sock,server,nowait and -serial unix:/tmp/serial-sock,server,nowait (or the paths configured in LM Studio settings). |
read_serial returns nothing | The guest may not be printing to the serial console. Verify the guest OS is configured to use the serial console. |
write_serial seems to do nothing | The guest may not be reading from the serial port at this moment. Check the VM state with query-status first. |
Build failed during npm install | The Rust toolchain (cargo) is required at install time. Install Rust from https://rustup.rs and run npm install again. |
These tools are useful when you want to plan, manage, monitor, and summarize VM tasks without leaving your chat.
| Tool | What it does | Key parameters |
|---|---|---|
execute_qmp | Runs a QMP command on the QEMU instance | qmp_command (string), qmp_arguments (JSON string) |
read_serial | Reads buffered output from the guest serial console | wait_for (optional), timeout_ms (default 5000), max_chars (optional), clear (default false) |
write_serial | Writes text to the guest serial console (simulates typing) | data (string), newline (default true) |
execute_qmp with query-status to see if the VM
is running, paused, or stopped.wait_for with read_serial when you expect a specific prompt (e.g. a login prompt or a boot
message). This makes the tool wait until that text appears.write_serial input small. Send one line or one short command at a time. Do not paste a huge
script in one call.newline to what the guest expects. Most prompts need a newline (leave newline: true).clear: true when you have read what you need and want to reset the serial buffer for a fresh
sequence of reads.-qmp and -serial flags.Goal: find out whether the VM is running.
{ "qmp_command": "query-status", "qmp_arguments": "{}" }
Goal: remove the CD image from the ide-cd0 drive.
{ "qmp_command": "eject", "qmp_arguments": "{\"device\": \"ide-cd0\"}" }
Goal: read the guest console and stop when you see a Login: prompt.
read_serial with wait_for: "Login:", timeout_ms: 30000.Login: prompt.-serial unix:/tmp/serial-sock,server,nowait.You want to install an operating system in the VM and drive it automatically.
Plan:
read_serial with wait_for to find the installer's first prompt (e.g. Press any key to boot...).write_serial to send the key (e.g. a newline or a letter) that advances the installer.read_serial to confirm the reboot message.execute_qmp with query-status to verify the VM is running after reboot.Tip: Keep a note of the exact prompt text you are waiting for. Small mismatches in wait_for will cause
timeouts.
You need to manage the VM's power state safely.
Plan:
execute_qmp → query-status to know the current state.execute_qmp → stop, then wait for the VM to halt using
read_serial or another query-status.execute_qmp → cont.You want to monitor the VM's resources and devices.
Plan:
execute_qmp with query-status for the basic running state.qmp_command) to query devices, memory, and CPU. For example,
query block devices to see which ISO is attached to which drive.| Problem | What to check |
|---|---|
| Tool returns an error about a socket | Make sure QEMU is running with -qmp unix:/tmp/qmp-sock,server,nowait and -serial unix:/tmp/serial-sock,server,nowait (or the paths configured in LM Studio settings). |
read_serial returns nothing | The guest may not be printing to the serial console. Verify the guest OS is configured to use the serial console. |
write_serial seems to do nothing | The guest may not be reading from the serial port at this moment. Check the VM state with query-status first. |
Build failed during npm install | The Rust toolchain (cargo) is required at install time. Install Rust from https://rustup.rs and run npm install again. |