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+
incusCLI installed and configureduvfor 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.