proxmox

This MCP server integrates with the Proxmox Virtual Environment API, exposing a range of capabilities as MCP tools. It supports managing virtual machines, LXC containers, storage, and cluster resources, all through a standardized Model Context Protocol interface. The server also implements an A2A (agent-to-agent) protocol profile, with an agent-card that details capabilities, authentication requirements, and a catalog of available operations. You can query the server to list VMs, fetch VM configurations and statuses, control VM power states, manage VM snapshots, list and manage containers, inspect cluster status, and monitor storage and tasks. The tooling is organized into categories such as Virtual Machine Tools, Container Tools, Storage Tools, Task Tools, and Cluster Tools, each exposing specific MCP endpoints like list_vms, get_vm_status, start_vm, list_containers, get_storage_status, get_cluster_status, and more. To use it, configure your MCP client (e.g., Claude Desktop) with the provided environment variables to authenticate to Proxmox, then call the corresponding tool names to perform operations against your Proxmox environment. The server is designed for automation workflows and multi-agent orchestration, enabling seamless integration with agent-based decision systems and cross-system automation pipelines.

Prerequisites:

• Python 3.10 or higher
• uv package manager (https://astral.sh/uv)
• Proxmox VE 6.0 or later

Install and set up:

1. Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone or download the repository, then navigate into it

# Example
git clone https://github.com/ry-ops/proxmox-mcp-server.git
cd proxmox-mcp-server

3. Run the setup script to create structure and install dependencies

chmod +x setup.sh
./setup.sh

4. Alternatively, manually create the project structure and synchronize dependencies

mkdir -p src/proxmox_mcp_server
# Place server.py and __init__.py in src/proxmox_mcp_server/
uv sync

5. Configure environment variables for Proxmox access (see Configuration section) and start using uv as described below.

Notes:

• Use API Token authentication for automation (recommended). Set PROXMOX_TOKEN_NAME and PROXMOX_TOKEN_VALUE and ensure the token has appropriate permissions.
• If you prefer password authentication, set PROXMOX_PASSWORD instead; tokens are generally more secure for automation.
• Ensure PROXMOX_HOST, PROXMOX_USER, and SSL verification (PROXMOX_VERIFY_SSL) reflect your environment. The default SSL behavior is to skip verification unless specified otherwise.
• The MCP configuration example uses an absolute path to the project directory in the --directory argument; adjust this to your deployment path.
• The server exposes a rich set of tools (list_vms, get_vm_status, start_vm, create_vm_snapshot, list_containers, get_cluster_status, etc.). Use these via your MCP client to build automated workflows.
• If you encounter connection or authentication errors, verify token permissions, token scoping, and that the Proxmox host is reachable from the server host.