home / mcp / sympathy mcp server

Sympathy MCP Server

Provides an MCP server for Incus VM operations with structured tools for VM control, file management, and VM lifecycle actions.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

Sympathy MCP Server enables structured, tool-based control over Incus VM operations through a dedicated MCP interface. It lets you run commands inside VMs, manage files, create and restore snapshots, and monitor VM status using a predefined set of MCP tools, avoiding ad-hoc Bash commands while providing reliable, auditable actions.

How to use

You will interact with Sympathy MCP Server through an MCP client, issuing requests that map to the nine built-in tools. Start the server using the provided runtime command, then issue MCP calls to execute commands, read or write files, manage snapshots, and observe VM state. Each operation is performed via a structured tool interface, ensuring predictable results and easy automation.

How to install

Prerequisites you need before installation:

Python 3.12+ needs to be installed and accessible on your system

Ensure the incus CLI is installed and can communicate with your virtualization environment

Install uv to manage Python project execution and MCP processes

Install and run Sympathy MCP Server with these steps:

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

# Or via entry point
uv run sympathy-mcp

Additional sections

Configuration and startup details are provided below to help you integrate Sympathy MCP Server into your environment. Follow the exact commands and JSON snippets to ensure proper MCP server setup and operation.

Configuration for MCP clients is defined in a JSON file that references the MCP server. The example below shows the required structure for registering Sympathy MCP as a local stdio MCP server.

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

Notes and troubleshooting

If you encounter issues starting the server, verify that Python 3.12+ is installed and accessible as the system default python3, the Incus CLI is properly configured, and uv is available for project management. Check that the path provided in the project flag points to the Sympathy-MCP project workspace.

Available tools

vm_exec

Execute a command inside a target VM, returning stdout, stderr, and exit code.

vm_file_read

Read the contents of a file from within a VM.

vm_file_write

Write content to a file inside a VM.

vm_file_push

Push a local file from the host into a VM.

vm_file_pull

Pull a file from a VM to the host.

vm_snapshot

Create a named snapshot of a VM state for safekeeping.

vm_restore

Restore a VM to a previously created named snapshot.

vm_status

Retrieve the VM’s current state, IP address, and resource usage.

vm_list

List all VMs with their status and basic details.