Metadata-Version: 2.4
Name: anyvm-mcp
Version: 0.1.0
Summary: MCP server for anyvm -- boot and manage BSD, illumos, Linux, Haiku, Android, Hurd, and Plan 9 VMs with natural language
Project-URL: Homepage, https://anyvm.org
Project-URL: Repository, https://github.com/anyvm-org/mcp
Project-URL: Issues, https://github.com/anyvm-org/mcp/issues
License: MIT License
        
        Copyright (c) 2026 Run Any VM anywhere - AnyVM.org
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,anyvm,bsd,haiku,illumos,linux,mcp,qemu,virtualization,vm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: mcp==1.27.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
Requires-Dist: pytest-mock==3.15.1; extra == 'dev'
Requires-Dist: pytest==9.0.2; extra == 'dev'
Description-Content-Type: text/markdown

# anyvm-mcp

> MCP server for **anyvm** -- boot and manage BSD, illumos, Linux, Haiku, Android, GNU Hurd, and Plan 9 VMs with natural language.
> Works with **Claude Code**, **GitHub Copilot**, and any other [MCP](https://modelcontextprotocol.io)-compatible AI assistant.

---

## Overview

**anyvm-mcp** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that bridges AI coding assistants with the [anyvm](https://anyvm.org) VM launcher.
anyvm boots prebuilt guest images under QEMU -- no manual installation, no libvirt. Once installed, your AI assistant can:

- Boot **FreeBSD, OpenBSD, NetBSD, DragonFly BSD, GhostBSD, MidnightBSD, Solaris, OmniOS, OpenIndiana, Tribblix, Haiku, Ubuntu, openEuler, BlissOS (Android), Debian GNU/Hurd, and Plan 9** guests in the background
- Target **x86_64, aarch64, riscv64, sparc64, powerpc64, s390x** and more (per-OS availability varies)
- **Execute commands** inside running VMs over SSH for instant diagnostics
- **Read the serial console** to debug boot failures
- Map **ports** and sync **folders** (rsync / sshfs / nfs / scp / 9p) between host and guest
- **Stop** VMs gracefully (guest shutdown with an ACPI fallback) or hard-kill via the QEMU monitor

The VM model mirrors the anyvm CLI: a VM is identified by its OS name plus
optional release (e.g. `freebsd` + `14.3`), not by user-invented names.
The first boot of an OS/release downloads the image from the matching
[anyvm-org builder](https://github.com/anyvm-org) release, so allow several
minutes; later boots reuse the cached image.

---

## Requirements

| Requirement | Notes |
|-------------|-------|
| Python >= 3.10 | |
| QEMU | `qemu-system-*` on PATH (anyvm can also self-download pinned builds for some guests) |
| OpenSSH client | `ssh` on PATH (used for exec/stop) |
| An MCP-compatible AI assistant | Claude Code, GitHub Copilot in VS Code, or any other MCP client |

> **Note:** The `anyvm.py` launcher is bundled automatically -- no separate installation needed.

---

## Installation

```bash
pipx install anyvm-mcp
```

Or with pip:

```bash
pip install anyvm-mcp
```

Or install from source:

```bash
git clone https://github.com/anyvm-org/mcp
cd mcp
pip install -e .
```

---

## Quickstart

### Claude Code

Add the server to `~/.claude/mcp.json` (or the project-level `.claude/mcp.json`):

```json
{
  "mcpServers": {
    "anyvm": {
      "command": "anyvm-mcp"
    }
  }
}
```

Restart Claude Code. You can now say things like:

> *"Boot a FreeBSD 14.3 VM with 2 CPUs and 2 GB RAM, then run uname -a in it."*

> *"My OpenBSD VM won't answer SSH. Show me the serial console output and suggest a fix."*

### GitHub Copilot (VS Code)

Add the server to `.vscode/mcp.json` in your workspace (or the user-level settings):

```json
{
  "servers": {
    "anyvm": {
      "type": "stdio",
      "command": "anyvm-mcp"
    }
  }
}
```

### Generic MCP client (HTTP/SSE)

Run anyvm-mcp as an HTTP server:

```bash
anyvm-mcp --transport sse --host 127.0.0.1 --port 8000
```

Then point your MCP client at `http://127.0.0.1:8000/sse`.

---

## CLI reference

```
usage: anyvm-mcp [-h] [--anyvm PATH] [--data-dir DIR]
                 [--transport {stdio,sse,streamable-http}]
                 [--host HOST] [--port PORT]

options:
  --anyvm PATH          Path to the anyvm launcher (default: bundled anyvm.py)
  --data-dir DIR        Directory for images, logs, and VM state (default: ~/.anyvm-mcp)
  --transport           MCP transport: stdio (default), sse, or streamable-http
  --host HOST           Bind host for HTTP transports (default: 127.0.0.1)
  --port PORT           Bind port for HTTP transports (default: 8000)
```

---

## Available tools

| Tool | Description |
|------|-------------|
| `list_supported_os` | Every guest OS anyvm can boot, with notes and SSH user |
| `start_vm` | Boot a guest in the background (os, release, arch, mem, cpus, ports, volumes, sync) |
| `list_running_vms` | Registered VMs with a live running/stopped probe |
| `vm_info` | State, SSH port/user/key, and serial-log path for one VM |
| `exec_in_vm` | Run a shell command over SSH inside a running VM |
| `stop_vm` | Graceful guest shutdown (SSH + ACPI fallback); `force` hard-kills via QEMU monitor |
| `console_output` | Tail the VM serial console log (works even when SSH is down) |

Notes:

- `start_vm` separates OS and release: `os="freebsd", release="14.3"` -- omit
  `release` for the builder's default release.
- Plan 9 (9front) guests have no SSH; `exec_in_vm` is unavailable for them.
  Use `console_output`, or the VNC web console anyvm prints at boot.
- Haiku's SSH user is `user`; all other guests use `root`.

---

## Example conversations

### Boot and inspect a VM

```
You:      Boot an OmniOS VM with 4 CPUs and 4 GB RAM and show me its uname.
Copilot:  [calls start_vm(os="omnios", cpus=4, mem_mb=4096)]
          VM omnios-r151054 is running (ssh -p 42761 root@127.0.0.1).
          [calls exec_in_vm(os="omnios", command="uname -a")]
          SunOS omnios 5.11 omnios-r151054 i86pc i386 i86pc
```

### Debug a boot failure

```
You:      My NetBSD VM never comes up on SSH. What's wrong?
Copilot:  [calls console_output(os="netbsd", lines=200)]
          The console shows the kernel waiting on root device selection...
```

### Cross-architecture testing

```
You:      Run my test script on Ubuntu riscv64.
Copilot:  [calls start_vm(os="ubuntu", arch="riscv64",
                          volumes=["/home/me/proj:/proj"], sync="rsync")]
          [calls exec_in_vm(os="ubuntu", command="cd /proj && sh run-tests.sh")]
```

---

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run a single test file
pytest tests/test_vm_manager.py -v
```

---

## License

MIT -- see [LICENSE](LICENSE).
