proxmox-mcp-server

<p align="center"> <img src="docs/hero.svg" width="100%" alt="You ask your assistant to clone VM 9000 to web-02 and start it; clone_vm and start_vm flow through proxmox-mcp-server to the Proxmox cluster, and the new VM lights up on pve2."> </p> <p align="center"> <a href="https://github.com/ry-ops/proxmox-mcp-server/releases"><img src="https://img.shields.io/github/v/release/ry-ops/proxmox-mcp-server?color=ff8a1f&label=release" alt="Release"></a> <img src="https://img.shields.io/badge/tools-340-ff8a1f" alt="340 tools"> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-3ec7ff" alt="Python 3.10+"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-1.x-b58cff" alt="MCP"></a> <a href="https://github.com/ry-ops/proxmox-mcp-server/pkgs/container/proxmox-mcp-server"><img src="https://img.shields.io/badge/docker-ghcr.io-3ddc84" alt="Docker image on ghcr.io"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-ffb02e" alt="MIT"></a> </p> <p align="center"><b>Talk to your Proxmox cluster.</b> A Model Context Protocol server that gives Claude, or any MCP client, the <b>whole Proxmox VE API</b>: 340 tools across VMs, containers, storage, clustering, Ceph, SDN and more.</p> <p align="center"> <a href="#talk">Talk to it</a> · <a href="#how">How it works</a> · <a href="#tools">340 tools</a> · <a href="#quick-start">Quick start</a> · <a href="#read-only">Read-only mode</a> · <a href="#a2a">A2A</a> · <a href="#troubleshooting">Troubleshooting</a> </p>

---

✨ Highlights

• 🧰 The whole API, not a demo. 340 tools across 14 areas: nodes, QEMU VMs, LXC containers, storage and backup, cluster and HA, access control, firewall, disks, Ceph, ACME, SDN, notifications, pools and appliances.
• 🖥️ Inside your guests too. Run commands through the QEMU guest agent (vm_agent_exec → vm_agent_exec_status) and read back the exit code and output.
• 🔒 Look-but-don't-touch with one switch. PROXMOX_READ_ONLY=true refuses every write inside the server, and 149 read-only tools keep working.
• 🔑 API tokens or passwords. Tokens are recommended; pair them with a PVEAuditor role for monitoring.
• 🐳 Runs anywhere. Use uv from a clone, or the multi-arch image on ghcr.io.
• 🤝 A2A-ready. agent-card.json lists every tool in 14 skill categories, for agent-to-agent discovery.
• 🛡️ Appliances. deploy_fortigate_vm builds a FortiGate-VM from Fortinet's KVM image, with WAN/LAN NICs on the bridges and VLANs you choose. deploy_cloud_vms builds cluster-ready VMs from a cloud image, with your SSH key and a static IP each, ready for k3s-mcp-server's create_cluster.

<a id="talk"></a>

💬 Talk to your cluster

<p align="center"> <img src="docs/chat.svg" width="100%" alt="A chat runs df -h inside VM 120 via the QEMU guest agent and shows the disk usage; a side panel cycles through more questions and the tools that answer them."> </p>

Once it's connected, just ask:

"Can you list all VMs in my Proxmox cluster?" "What's the status of VM 100 on node pve1?" "Create a snapshot called 'backup-2025' for VM 100 on pve1." "Show me the storage usage on all nodes." "List all running tasks in the cluster." "Clone VM 9000 to a new VM called web-02 and start it." "Run df -h inside VM 120 using the guest agent and show me the output." "Make three Ubuntu VMs on pve1 at 192.168.1.181–183 with my SSH key, ready for a K3s cluster."

There are more worked examples in USAGE.md.

<a id="how"></a>

⚙️ How it works

<p align="center"> <img src="docs/how-it-works.svg" width="100%" alt="MCP clients talk to proxmox-mcp-server over stdio; the server calls the Proxmox VE API over HTTPS on port 8006. With read-only mode on, GET requests pass and POST, PUT and DELETE are refused inside the server."> </p>

• Your MCP client (Claude Desktop, Claude Code, or anything that speaks MCP) starts the server and talks to it over stdio.
• The server (Python, httpx, the MCP SDK) turns each tool call into a request to the Proxmox VE REST API over HTTPS on port 8006, authenticated with an API token or a password.
• Read-only mode is checked in the server's HTTP client, so a refused write never leaves your machine.

<a id="tools"></a>

🧰 340 tools, 14 areas

<p align="center"> <img src="docs/tools.svg" width="100%" alt="A tile map of the 340 tools by API area: QEMU VMs 46, nodes 38, cluster and HA 37, access control 33, Ceph 33, firewall 31, LXC 28, notifications 23, disks 17, ACME 17, SDN 16, storage and backup 14, pools 5, appliances 2."> </p>

| Area | Tools | Highlights | |------|------:|------------| | Nodes | 38 | Status, config, DNS/hosts/time, network interfaces, services, APT updates, syslog, power | | QEMU VMs | 46 | Lifecycle, create/clone/delete, config, snapshots, migration, disk resize/move, RRD metrics, guest agent (vm_agent_exec, vm_agent_exec_status), VNC proxy | | LXC containers | 28 | Lifecycle, create/clone/delete, config, snapshots, migration, resize | | Storage & backup | 14 | Storage definitions, content and volumes, URL downloads, vzdump backup and restore | | Cluster | 37 | Status, resources, options, log, tasks, HA resources/groups, replication, backup jobs | | Access control | 33 | Users, API tokens, groups, roles, ACLs, realms | | Firewall | 31 | Cluster and node rules, security groups, aliases, IP sets, macros, logs (per-VM and per-container rules are in the guest modules) | | Disks | 17 | SMART, wipe, GPT init, LVM, LVM-thin, ZFS, directory storage | | Ceph | 33 | Status, OSDs, monitors, managers, MDS, pools, flags, CRUSH | | ACME & certificates | 17 | ACME accounts and plugins, node certificate ordering, custom certs | | SDN | 16 | Zones, VNets, subnets, apply | | Notifications | 23 | Gotify, sendmail, SMTP and webhook endpoints, matchers | | Pools | 5 | Resource pool CRUD | | Appliances | 2 | deploy_fortigate_vm: FortiGate-VM from Fortinet's KVM image, WAN/LAN NICs on chosen bridges and VLANs, sized for the free evaluation license. deploy_cloud_vms: VMs from a cloud image (e.g. Ubuntu's) with cloud-init user, SSH key and a static IP or DHCP each, disk grown and started |

Tool names follow the Proxmox API: list_*, get_*, create_*, update_*/set_*, delete_*, plus actions such as start_vm, migrate_container or apply_sdn. Each area is one module in proxmox_mcp/tools/. Your MCP client shows every tool with its full input schema, or you can list them all locally:

uv run python -c "from proxmox_mcp.server import ALL_TOOLS; print('\n'.join(sorted(t.name for t in ALL_TOOLS)))"

Handy recipes

| Task | Tools | |------|-------| | Inventory | list_nodes, get_cluster_resources, list_vms, list_containers, list_storage | | VM lifecycle | start_vm, shutdown_vm, stop_vm, reboot_vm, create_vm, clone_vm, migrate_vm | | Disk images | download_url_to_storage with content=import, then create_vm with scsi0=local-lvm:0,import-from=local:import/<image>, or import_vm_disk | | Snapshots | create_vm_snapshot, list_vm_snapshots, rollback_vm_snapshot, delete_vm_snapshot | | Monitoring | get_node_status, get_vm_status, get_vm_rrddata, get_node_storage_status | | Tasks | list_cluster_tasks, list_node_tasks, get_task_status, get_task_log | | Guest agent | vm_agent_exec (returns a PID), then vm_agent_exec_status for the exit code and output | | Cluster nodes | download_url_to_storage for a cloud image with content=import, then deploy_cloud_vms; hand the IPs to k3s-mcp-server's create_cluster |

<a id="quick-start"></a>

🚀 Quick start

You need Python 3.10+ with uv, or Docker, and Proxmox VE 6.0 or later.

1. Make an API token. In the Proxmox UI, go to Datacenter → Permissions → API Tokens → Add. For full access, uncheck Privilege Separation so the token inherits your user's permissions. Copy the secret; you won't see it again. The full token ID looks like root@pam!automation.

2. Run the server with one of these:

<details open> <summary><b>uv, from a clone</b></summary>

curl -LsSf https://astral.sh/uv/install.sh | sh     # if you don't have uv
git clone https://github.com/ry-ops/proxmox-mcp-server && cd proxmox-mcp-server
./setup.sh                                          # or: uv sync

export PROXMOX_HOST="192.168.1.100"
export PROXMOX_USER="root@pam"
export PROXMOX_TOKEN_NAME="automation"
export PROXMOX_TOKEN_VALUE="your-token-here"
./test-connection.sh                                # checks connection, auth and permissions

A .env file in the project directory is loaded automatically; see .env.example.

</details> <details> <summary><b>Docker</b></summary>

A multi-arch image is published to GitHub Container Registry on every push to main and for each release tag:

docker pull ghcr.io/ry-ops/proxmox-mcp-server:latest   # or a version tag, e.g. :2.4.0
docker run -i --rm --env-file .env ghcr.io/ry-ops/proxmox-mcp-server:latest

MCP clients talk over stdio, so run the container interactively (-i). docker-compose.yaml does the same using your .env.

</details>

3. Connect your MCP client. For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%/Claude/claude_desktop_config.json on Windows:

<details open> <summary><b>uv + API token (recommended)</b></summary>

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "automation",
        "PROXMOX_TOKEN_VALUE": "your-token-value-here"
      }
    }
  }
}

Use the absolute path to your clone.

</details> <details> <summary><b>uv + password</b></summary>

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_PASSWORD": "your-password-here"
      }
    }
  }
}

</details> <details> <summary><b>Docker</b></summary>

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST", "-e", "PROXMOX_USER", "-e", "PROXMOX_TOKEN_NAME", "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/ry-ops/proxmox-mcp-server:latest"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "automation",
        "PROXMOX_TOKEN_VALUE": "your-token-value-here"
      }
    }
  }
}

</details>

4. Restart your client completely (quit it, don't just close the window), and ask it to list your VMs. More detail in QUICKSTART.md and SETUP.md.

🔧 Configuration

| Variable | Required | Default | What it does | |---|:---:|---|---| | PROXMOX_HOST | ✅ | | Hostname or IP, without scheme or port (192.168.1.100, not https://192.168.1.100:8006) | | PROXMOX_USER | ✅ | | e.g. root@pam, admin@pve | | PROXMOX_TOKEN_NAME + PROXMOX_TOKEN_VALUE | one of | | API token auth (recommended) | | PROXMOX_PASSWORD | one of | | Password auth | | PROXMOX_PORT | | 8006 | API port | | PROXMOX_VERIFY_SSL | | false | Verify the server's TLS certificate | | PROXMOX_READ_ONLY | | false | Refuse every write; see below |

<a id="read-only"></a>

🔒 Read-only mode and security

PROXMOX_READ_ONLY=true makes the server look-but-don't-touch. Only GET requests are sent, and every create,