Sympathy-MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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 |
| Run a command inside a VM (stdout, stderr, exit code) |
| Read a file from inside a VM |
| Write content to a file inside a VM |
| Push a file from host into a VM |
| Pull a file from a VM to host |
| Create a named snapshot |
| Restore to a named snapshot |
| Get VM state, IP, resource usage |
| List all VMs with status |
Related MCP server: VMWare-MCP-server-for-LLMs
Usage
# Run the MCP server (stdio transport)
uv run python -m sympathy_mcp
# Or via entry point
uv run sympathy-mcpMCP 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.
Available Tools
9 toolsvm_execA
Execute a command on a remote host via SSH.
Runs the command via `sh -c` so shell features (pipes, redirects, etc.)
work as expected. Captures both stdout and stderr.
Args:
vm: Name of the host (as configured in hosts.toml).
command: Shell command to execute.
workdir: Working directory on the remote host (default: /).
timeout: Maximum seconds to wait (default: 120).
Returns:
Command output with stdout, stderr, and exit code.
Inputs: vm (required), command (required), workdir, timeout. Returns: result
vm_file_pullA
Pull a file from a remote host to the local host via SCP.
Args:
vm: Name of the host (as configured in hosts.toml).
remote_path: Absolute path to the file on the remote host.
local_path: Destination path on the local host.
Returns:
Success confirmation or error message.
Inputs: vm (required), remote_path (required), local_path (required). Returns: result
vm_file_pushA
Push a file from the local host to a remote host via SCP.
Args:
vm: Name of the host (as configured in hosts.toml).
local_path: Path to the file on the local host.
remote_path: Absolute destination path on the remote host.
Returns:
Success confirmation or error message.
Inputs: vm (required), local_path (required), remote_path (required). Returns: result
vm_file_readA
Read a file from a remote host via SSH.
Args:
vm: Name of the host (as configured in hosts.toml).
path: Absolute path to the file on the remote host.
Returns:
File contents as a string, or an error message.
Inputs: vm (required), path (required). Returns: result
vm_file_writeA
Write content to a file on a remote host via SSH.
Handles arbitrary content safely by piping through SSH stdin.
Args:
vm: Name of the host (as configured in hosts.toml).
path: Absolute path where the file should be written.
content: The content to write to the file.
Returns:
Success confirmation or error message.
Inputs: vm (required), path (required), content (required). Returns: result
vm_listA
List all available VMs and containers with their status (Incus).
Returns:
Formatted list of all instances, or a message if none exist.
Inputs: no named parameters. Returns: result
vm_restoreB
Restore a VM/container to a named snapshot (Incus).
Args:
vm: Name of the VM or container.
snapshot: Name of the snapshot to restore.
Returns:
Success confirmation or error message.
Inputs: vm (required), snapshot (required). Returns: result
vm_snapshotA
Create a snapshot of a VM/container (Incus).
Args:
vm: Name of the VM or container.
name: Name for the snapshot (alphanumeric, hyphens, underscores).
Returns:
Success confirmation or error message.
Inputs: vm (required), name (required). Returns: result
vm_statusA
Get the status of a VM/container (Incus).
Returns state (running/stopped), IP address, resource usage,
and available snapshots.
Args:
vm: Name of the VM or container.
Returns:
Formatted status information or error message.
Inputs: vm (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose with no ambiguity. The tools cover separate operations: command execution, file transfer (pull/push), file reading/writing, listing instances, snapshot management, and status checking. The descriptions clearly differentiate between these functions, making misselection unlikely.
All tools follow a consistent 'vm_' prefix with descriptive action suffixes (e.g., vm_exec, vm_file_pull, vm_snapshot). The naming pattern is perfectly uniform throughout the set, using snake_case consistently without any deviations or mixed conventions.
With 9 tools, this is well-scoped for remote host/VM management. Each tool earns its place by covering essential operations like execution, file management, snapshot handling, and status monitoring. The count is neither too thin nor excessive for the domain.
The toolset provides complete coverage for remote VM/container management. It includes execution, bidirectional file transfer, file reading/writing, instance listing, snapshot creation/restoration, and status checking. There are no obvious gaps or missing operations that would hinder agent workflows.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Superserve sandboxes: create, exec, and manage Firecracker microVMs
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server for managing Incus containers and VMs via the incus CLI. Supports operations on remotes, instances, images, networks, storage, profiles, projects, and snapshots.-
- FlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents direct access to VMware vSphere infrastructure, enabling VM lifecycle management, snapshots, datastore operations, networking, and more via 55 typed tools built on govc.-
- AlicenseNot gradedqualityCmaintenanceMCP server providing AI agents with persistent shells, filesystem access, and multi-machine management backed by Docker containers or remote SSH hosts.1AGPL 3.0
- AlicenseAqualityBmaintenanceAn MCP server that exposes Runloop Devbox operations as tools, enabling AI agents to create and manage Linux sandboxes, execute commands, edit files, snapshot disks, and drive interactive PTY sessions.16MIT