anyvm-mcp

MCP server for anyvm — run, manage, and debug BSD/Illumos VMs with natural language. Works with Claude Code, GitHub Copilot, and any other MCP-compatible AI assistant.

Overview

anyvm-mcp is a Model Context Protocol (MCP) server that bridges AI coding assistants with the anyvm VM manager. Once installed, your AI assistant can:

• 🖥️ Create FreeBSD, OpenBSD, NetBSD, OmniOS, and other BSD/Illumos VMs in seconds
• 🚀 Start / Stop / Destroy VMs on demand
• 🔍 Inspect VM state, IPs, CPU, memory, and network configuration
• 💻 Execute commands inside running VMs for instant diagnostics
• 📜 Read console output to debug boot failures or system errors
• 📸 Snapshot and restore VMs to safe checkpoints

Requirements

Note: The anyvm CLI is bundled automatically — no separate installation needed.

Installation

pipx install anyvm-mcp

Or with pip:

pip install anyvm-mcp

Or install from source:

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):

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

Restart Claude Code. You can now say things like:

"Create a FreeBSD 14 VM called 'dev' with 2 CPUs and 2 GB RAM, then show me its IP."

"My OpenBSD VM won't boot. Show me the 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):

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

Generic MCP client (HTTP/SSE)

Run anyvm-mcp as an HTTP server:

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] [--transport {stdio,sse,streamable-http}]
                   [--host HOST] [--port PORT]

options:
  --anyvm PATH          Path to the anyvm binary (default: bundled version)
  --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

Example conversations

Creating and inspecting a VM

You:      Create an OmniOS VM called "omnios-test" with 4 CPUs, 4 GB RAM, and 40 GB disk.
Copilot:  ✅ VM "omnios-test" created. State: stopped.
          Run `start_vm` to boot it.

You:      Start it and tell me its IP address.
Copilot:  ✅ VM started. IP: 192.168.100.42

Debugging a boot failure

You:      My FreeBSD VM "bsd-web" won't respond to SSH. What's wrong?
Copilot:  [calls console_output("bsd-web", lines=200)]
          The console log shows a panic in vtnet0 — likely a driver issue.
          Try: exec_in_vm("bsd-web", "sysctl hw.vtnet.0.csum_disable=1")

Snapshot workflow

You:      Snapshot "bsd-web" before I upgrade it.
Copilot:  [calls create_snapshot("bsd-web", "pre-upgrade", description="before pkg upgrade")]
          ✅ Snapshot "pre-upgrade" created.

You:      The upgrade broke something. Roll back.
Copilot:  [calls restore_snapshot("bsd-web", "pre-upgrade")]
          ✅ Restored to snapshot "pre-upgrade".

Development

# 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.