ry-ops/proxmox-mcp-server: MCP server for managing Proxmox Virtual Environment VMs, containers, storage, and cluster resources

MCP server for managing Proxmox Virtual Environment VMs, containers, storage, and cluster resources - ry-ops/proxmox-mcp-server

Summary

proxmox-mcp-server is a Python Model Context Protocol (MCP) server that exposes the Proxmox VE REST API to MCP clients such as Claude Desktop or Claude Code. It ships 339 tools across 14 areas, including nodes, QEMU VMs, LXC containers, storage, clustering, Ceph, SDN, firewall, and ACME certificates, so an AI assistant can list, inspect, and mutate Proxmox resources through natural-language requests. Communication runs over stdio from the MCP client to the server, which then calls the Proxmox API over HTTPS on port 8006 using either an API token or password.

What it is useful for

It is useful for engineers who want to drive a Proxmox cluster from an MCP-capable assistant instead of writing one-off scripts. The README documents concrete workflows: cloning VM 9000 into web-02 and starting it, creating a snapshot called backup-2025 for VM 100 on pve1, running df -h inside VM 120 through the QEMU guest agent (vm_agent_exec then vm_agent_exec_status), and monitoring with get_node_status, get_vm_rrddata, or list_cluster_tasks.

A PROXMOX_READ_ONLY=true flag blocks every write inside the HTTP client before it leaves the machine, leaving 149 read-only tools available, which is useful for a monitoring dashboard or auditor role. The repository also publishes an agent-card.json listing all 339 tools in 14 skill categories for agent-to-agent discovery, and includes a deploy_fortigate_vm appliance tool that builds a FortiGate-VM from Fortinet's KVM image.

Documented limitations: the project depends on mcp>=1.0.0,<2, so MCP 2.x is not yet supported; streamable-HTTP transport is on the roadmap, not shipped; and vm_agent_ping, get_vm_vnc_proxy, and get_vm_spice_proxy are blocked in read-only mode because they use POST. The token's permissions are the real authorization boundary, so destructive operations are reachable to any connected client.

How engineers can use it

Setup requires Python 3.10+ with uv (or Docker) and Proxmox VE 6.0 or later. The README's quick start:

1. Create an API token in the Proxmox UI under Datacenter → Permissions → API Tokens. Uncheck Privilege Separation if you want the token to inherit your user's permissions, and copy the secret.
2. Clone the repo and run ./setup.sh (or uv sync), then export PROXMOX_HOST, PROXMOX_USER, PROXMOX_TOKEN_NAME, and PROXMOX_TOKEN_VALUE. A .env file in the project directory is loaded automatically. Run ./test-connection.sh to verify auth, permissions, and API reachability.
3. Add the server to your MCP client. For Claude Desktop, edit claude_desktop_config.json with an absolute path to the clone and the four environment variables, then restart the client completely.

A Docker image is published to ghcr.io/ry-ops/proxmox-mcp-server for multi-arch use, and docker-compose.yaml is included. For monitoring-only deployments, combine PROXMOX_READ_ONLY=true with a token holding the PVEAuditor role. The README points to QUICKSTART.md, SETUP.md, and USAGE.md for deeper detail.