How do I use Sympathy-MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Sympathy-MCP Check the status and IP address of my 'dev-machine' VM" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Sympathy-MCP

MCP server for Incus VM operations. Named for sympathetic magic — the connection between puppet and puppeteer.

Agents on masternode puppeteer VMs via structured MCP tools instead of freeform Bash commands.

Tools

Tool	Description
`vm_exec`	Run a command inside a VM (stdout, stderr, exit code)
`vm_file_read`	Read a file from inside a VM
`vm_file_write`	Write content to a file inside a VM
`vm_file_push`	Push a file from host into a VM
`vm_file_pull`	Pull a file from a VM to host
`vm_snapshot`	Create a named snapshot
`vm_restore`	Restore to a named snapshot
`vm_status`	Get VM state, IP, resource usage
`vm_list`	List all VMs with status

Usage

# Run the MCP server (stdio transport)
uv run python -m sympathy_mcp

# Or via entry point
uv run sympathy-mcp

MCP Configuration

Add to .mcp.json:

{
  "mcpServers": {
    "sympathy-mcp": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/Sympathy-MCP", "sympathy-mcp"]
    }
  }
}

Requirements

Python 3.12+
incus CLI installed and configured
uv for project management

Architecture

src/sympathy_mcp/incus.py — Async Incus CLI wrapper (validation, subprocess exec, structured results)
src/sympathy_mcp/server.py — FastMCP server with 9 tools (stdio transport)

Shells out to incus CLI under the hood. Go rewrite planned.