Proxmox MCP Server

Manage your Proxmox VE infrastructure using AI. Pilotez votre infrastructure Proxmox VE grâce à l'IA.

This MCP (Model Context Protocol) server allows LLMs (like Claude, Gemini, etc.) to securely monitor and control your Proxmox nodes, VMs, and containers.

🌟 Features

• 📊 Monitoring: View nodes (CPU/RAM), VMs, containers (LXC), storage status, and internal IPs (via Agent).
• ⚡ Management: Start, stop (graceful/forced), reboot, and Clone (Provisioning) machines.
• 🏗️ Orchestration: Migrate machines (live or offline) between nodes in a cluster.
• 📈 Analytics: View Historical Performance (CPU/RAM RRD data) for diagnostics.
• 📚 Library: Manage LXC Templates and ISOs (Download/List).
• 🏷️ Organization: Manage machine Tags.
• 🛠️ DevOps: Configure Cloud-Init (User/SSH/IP), Resize resources (CPU/RAM Hotplug), and Download ISOs.
• 🛡️ Security: Audit and manage Firewall rules per VM/Container.
• 🛡️ Protection: Manage Snapshots and Backups directly via MCP.
• 🎨 LobeChat Ready: Compatible with LobeChat Plugins via a dedicated REST API.
• 🔗 Access: Generate direct links to the NoVNC Console.
• 🔒 Secure: Uses Proxmox API Tokens. Machine deletion is disabled for safety.
• 🐳 Docker-ready: Works instantly with docker run.

🛠️ Tool Reference

📊 Monitoring & Diagnostics

Tool	Description
list_infrastructure	Shows node status (CPU, RAM, Online/Offline).
list_machines	Lists VMs and Containers (Filters: name, status, type).
get_machine_config	Shows detailed config (Cores, Memory, Disks).
list_storage	Shows usage & capabilities (Filter: content_filter).
get_vm_agent_network	Retrieves internal IPs via QEMU Agent.
get_cluster_logs	Shows global cluster error logs.
get_machine_performance_history	Retrieves RRD history (CPU/RAM trends).

⚡ Control & Actions

Tool	Description
start_machine	Starts a VM or Container.
stop_machine	Stops (Graceful Shutdown or Forced Stop) a machine.
reboot_machine	Reboots a machine.
get_console_url	Generates a direct link to the NoVNC console.
resize_resources	Adjusts CPU or RAM (Hotplug if supported).
unlock_machine	Unlocks a machine (removes lock file).
set_machine_tags	Sets tags (e.g., "prod,db").

🏗️ Provisioning & DevOps

Tool	Description
clone_machine	Clones a machine (Template) to a new ID.
set_cloudinit_config	Configures User, Password, SSH, IP via Cloud-Init.
list_isos	Lists available ISO files.
download_iso	Downloads an ISO from a URL.
list_available_lxc_templates	Lists system templates (Alpine, Ubuntu...).
download_lxc_template	Downloads an LXC template.

🛡️ Security & Protection

Tool	Description
list_snapshots	Lists restore points.
create_snapshot	Creates an instant snapshot.
rollback_snapshot	Restores a snapshot.
delete_snapshot	Deletes a snapshot to free space.
list_backups	Lists full backups (vzdump).
create_backup	Starts a full backup.
list_firewall_rules	Lists firewall rules.
add_firewall_rule	Adds a rule (ACCEPT/DROP) to the firewall.

🏗️ Orchestration (Cluster)

Tool	Description
migrate_machine	Moves a machine to another node (Live/Offline).

📚 Documentation

Please select your language / Veuillez choisir votre langue :

• 🇫🇷 Documentation en Français
• 🇺🇸 English Documentation

🔑 Proxmox API Token

To use this server, you need a Proxmox API Token. Pour utiliser ce serveur, vous avez besoin d'un Token API Proxmox.

1. Datacenter > Permissions > API Tokens > Add.
2. Select user, set ID (e.g., mcp), and uncheck "Privilege Separation".
3. Copy the Token ID and Secret.

⚙️ Environment Variables

Variable	Description	Example
PROXMOX_URL	URL of your Proxmox server	https://192.168.1.10:8006
PROXMOX_USER	User (usually root@pam)	root@pam
PROXMOX_TOKEN_ID	API Token Name (just the name)	mcp_token
PROXMOX_TOKEN_SECRET	API Token Secret	xxxxxxxx-xxxx-xxxx...
PROXMOX_VERIFY_SSL	Verify SSL Certificate	false (for self-signed)

🚀 Quick Start (Docker)

1. Clone this repo.
2. Copy .env.example to .env and fill in your Proxmox credentials.
3. Run:

   docker-compose up -d --build
   

4. Configure your MCP client (Claude Desktop, Cursor, Gemini-CLI) to use the Docker container.

(See detailed instructions in the links above)

📦 Project Structure

mcp_proxmox/
├── docs/               # Documentation (FR/EN)
├── src/                # Python Source Code
├── .env.example        # Configuration Template
├── Dockerfile          # Docker Configuration
└── docker-compose.yml  # Docker Compose Configuration