Skip to main content
Glama

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

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

Available Tools

9 tools
vm_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

    A4.1/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for managing Incus containers and VMs via the incus CLI. Supports operations on remotes, instances, images, networks, storage, profiles, projects, and snapshots.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server providing AI agents with persistent shells, filesystem access, and multi-machine management backed by Docker containers or remote SSH hosts.
      1
      AGPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      16
      MIT