Proxmox MCP Server
Manages Proxmox VE infrastructure — VMs, LXC containers, snapshots, storage, node monitoring, tasks, SSH access, user management, and guest agent commands.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Proxmox MCP Server list all VMs on node pve"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Proxmox MCP Server
A Model Context Protocol (MCP) server that enables Claude to manage Proxmox VE infrastructure — VMs, LXC containers, snapshots, storage, and more.
Features
Node Management — List cluster nodes, monitor CPU/RAM/disk metrics
VM & Container Control — Start, stop, reboot, destroy QEMU VMs and LXC containers
Snapshots — Create, list, delete, and rollback snapshots
Storage — Browse storage pools and content (ISOs, backups, templates)
Task Monitoring — Track Proxmox tasks in real-time
SSH Access — Execute commands directly on Proxmox host
User Management — Create, update, delete Proxmox users
Guest Agent — Execute commands inside VMs via QEMU Guest Agent
Docker Ready — Run as a container with minimal configuration
Related MCP server: ProxmoxEmCP
Quick Start with Docker Compose
Step 1: Clone the repository
git clone https://github.com/BenjaminDuthe/proxmox-mcp.git
cd proxmox-mcpStep 2: Create your configuration file
cp .env.example .envStep 3: Edit .env with your Proxmox credentials
Open .env in your editor and replace the placeholder values:
# ⚠️ REQUIRED - Replace these values with your own
PROXMOX_HOST=<YOUR_PROXMOX_IP> # Example: 192.168.1.10
PROXMOX_PORT=8006 # Default Proxmox port (usually no change needed)
PROXMOX_TOKEN_ID=<YOUR_TOKEN_ID> # Example: root@pam!mcp
PROXMOX_TOKEN_SECRET=<YOUR_TOKEN_SECRET> # Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
PROXMOX_VERIFY_SSL=false # Set to 'true' if you have valid SSL certificates
PROXMOX_TIMEOUT=30
# 📌 OPTIONAL - For SSH access to Proxmox host
PROXMOX_SSH_USER=root
PROXMOX_SSH_KEY_PATH=<PATH_TO_YOUR_SSH_KEY> # Example: ~/.ssh/id_rsa📋 Legend:
<YOUR_PROXMOX_IP>→ Your Proxmox server IP address (e.g.,192.168.1.10)
<YOUR_TOKEN_ID>→ API token ID created in Proxmox (e.g.,root@pam!mytoken)
<YOUR_TOKEN_SECRET>→ The secret shown when creating the token (UUID format)
<PATH_TO_YOUR_SSH_KEY>→ Path to your SSH private key (optional, for SSH tools)
Step 4: Generate SSH key (optional, for SSH tools)
If you want to use SSH tools (ssh_execute, ssh_read_file, etc.):
# Generate a dedicated SSH key
ssh-keygen -t ed25519 -f ~/.ssh/id_proxmox_mcp -N "" -C "proxmox-mcp"
# Copy the public key to your Proxmox server
ssh-copy-id -i ~/.ssh/id_proxmox_mcp.pub root@<YOUR_PROXMOX_IP>Then update .env:
PROXMOX_SSH_KEY_PATH=~/.ssh/id_proxmox_mcpStep 5: Start with Docker Compose
docker compose up -dWhat happens:
Docker builds the
proxmox-mcpimage from the DockerfileThe container starts with your
.envconfigurationSSH key is mounted read-only inside the container
MCP server is ready to receive commands
Step 6: Check it's running
# View logs
docker compose logs
# Expected output:
# proxmox-mcp | INFO - Configuration loaded: 192.168.1.10:8006
# proxmox-mcp | INFO - Proxmox client connected
# proxmox-mcp | INFO - MCP server readyStep 7: Stop/Restart
# Stop
docker compose down
# Restart (after .env changes)
docker compose up -d --force-recreate
# Rebuild (after code changes)
docker compose up -d --buildDocker Compose File Explained
The docker-compose.yml file:
services:
proxmox-mcp:
build: . # Build image from local Dockerfile
image: proxmox-mcp:latest # Image name
container_name: proxmox-mcp # Container name
stdin_open: true # Keep STDIN open (required for MCP protocol)
tty: true # Allocate pseudo-TTY
env_file:
- .env # Load environment variables from .env file
environment:
# Override SSH key path for container filesystem
- PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp
volumes:
# Mount your SSH key inside the container (read-only)
- ~/.ssh/id_proxmox_mcp:/home/mcp/.ssh/id_proxmox_mcp:ro
restart: unless-stopped # Auto-restart on failureKey points:
stdin_open+ttyare required because MCP uses stdio for communication.envfile is loaded automatically (never committed to git)SSH key is mounted at
/home/mcp/.ssh/(container runs as non-rootmcpuser):romeans read-only (security best practice)
Alternative: Run with Docker (without Compose)
# Build the image
docker build -t proxmox-mcp .
# Run with .env file
docker run --rm -it --env-file .env proxmox-mcp
# Run with SSH key mounted
docker run --rm -it \
--env-file .env \
-e PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp \
-v ~/.ssh/id_proxmox_mcp:/home/mcp/.ssh/id_proxmox_mcp:ro \
proxmox-mcpAlternative: Local Installation (without Docker)
# Install Python package
pip install -e ".[dev]"
# Run MCP server
python -m proxmox_mcp.serverConfiguration Reference
Environment Variables
Variable | Description | Required | Default |
| Proxmox server IP or hostname | Yes | — |
| API port | No |
|
| API token ID ( | Yes* | — |
| API token secret (UUID) | Yes* | — |
| Username (alternative to token) | Yes* | — |
| Password (alternative to token) | Yes* | — |
| Verify SSL certificate | No |
|
| Request timeout (seconds) | No |
|
| Path to SSH private key | No | — |
| SSH username | No |
|
* Either
TOKEN_ID+TOKEN_SECRETORUSER+PASSWORDis required. Token is recommended.
Creating an API Token in Proxmox
Open Proxmox web interface (https://your-proxmox:8006)
Go to Datacenter → Permissions → API Tokens
Click Add
Fill in:
User:
root@pam(or your user)Token ID:
mcp(or any name you want)Privilege Separation: ⚠️ Uncheck this to inherit user permissions
Click Add
Copy the token secret immediately (shown only once!)
Your token ID will be: root@pam!mcp
Claude Desktop Configuration
Option 1: With Docker (recommended)
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"proxmox": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "<PATH_TO_PROJECT>/.env",
"-e", "PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp",
"-v", "<PATH_TO_SSH_KEY>:/home/mcp/.ssh/id_proxmox_mcp:ro",
"proxmox-mcp"
]
}
}
}Replace:
<PATH_TO_PROJECT>→ Full path to the cloned repository (e.g.,/home/user/proxmox-mcp)
<PATH_TO_SSH_KEY>→ Full path to your SSH private key (e.g.,/home/user/.ssh/id_proxmox_mcp)
Option 2: With Python (local install)
{
"mcpServers": {
"proxmox": {
"command": "python",
"args": ["-m", "proxmox_mcp.server"],
"cwd": "<PATH_TO_PROJECT>",
"env": {
"PROXMOX_HOST": "<YOUR_PROXMOX_IP>",
"PROXMOX_TOKEN_ID": "<YOUR_TOKEN_ID>",
"PROXMOX_TOKEN_SECRET": "<YOUR_TOKEN_SECRET>",
"PROXMOX_VERIFY_SSL": "false"
}
}
}
}Replace:
<PATH_TO_PROJECT>→ Full path to the cloned repository
<YOUR_PROXMOX_IP>→ Your Proxmox server IP
<YOUR_TOKEN_ID>→ Your API token ID (e.g.,root@pam!mcp)
<YOUR_TOKEN_SECRET>→ Your API token secret
Available Tools
Nodes
Tool | Description |
| List all cluster nodes with CPU/RAM/disk metrics |
| Get detailed status of a specific node |
Virtual Machines (QEMU)
Tool | Description |
| List all VMs with status and resource usage |
| Get full VM configuration |
| Start a VM |
| Force stop a VM |
| Graceful shutdown (ACPI) |
| Reboot a VM |
| Permanently delete a VM and its disks |
Containers (LXC)
Tool | Description |
| List all LXC containers |
| Get full container configuration |
LXC containers support the same start/stop/shutdown/reboot/destroy operations as VMs.
Snapshots
Tool | Description |
| List snapshots of a VM/container |
| Create a new snapshot |
| Delete a snapshot |
| Restore VM/container to a snapshot |
Storage
Tool | Description |
| List storage pools with usage stats |
| List content (ISOs, backups, images) |
Tasks
Tool | Description |
| List recent Proxmox tasks |
| Get detailed task status by UPID |
SSH (Proxmox Host)
Tool | Description |
| Execute command on Proxmox host |
| Read file from Proxmox host |
| Write file to Proxmox host |
| Fix APT repos for non-subscription |
Users
Tool | Description |
| List all Proxmox users |
| Get user details and tokens |
| Create a new user |
| Update user properties |
| Delete a user |
Guest Agent (VM)
Tool | Description |
| Execute command inside VM |
| Get async command result |
| Execute command and wait for result |
| Read file from inside VM |
| Write file inside VM (protected paths) |
Troubleshooting
"Connection refused" error
Check that
PROXMOX_HOSTis correctVerify Proxmox API is accessible:
curl -k https://<YOUR_PROXMOX_IP>:8006/api2/jsonCheck firewall rules on Proxmox
"Authentication failed" error
Verify
PROXMOX_TOKEN_IDformat:user@realm!tokenname(e.g.,root@pam!mcp)Check token secret is correct (no extra spaces)
Ensure "Privilege Separation" is unchecked on the token
SSH tools not working
Check SSH key path is correct in
.envVerify key is authorized on Proxmox:
ssh -i ~/.ssh/id_proxmox_mcp root@<YOUR_PROXMOX_IP>In Docker, ensure the volume mount path matches
PROXMOX_SSH_KEY_PATH
Docker: "permission denied" on SSH key
Ensure the SSH key file has correct permissions:
chmod 600 ~/.ssh/id_proxmox_mcpThe container runs as
mcpuser (UID 1000)
Architecture
src/proxmox_mcp/
├── server.py # MCP server entry point
├── client.py # Async Proxmox API client (httpx)
├── ssh_client.py # Async SSH client (asyncssh)
├── config.py # Environment-based configuration
├── models.py # Pydantic models
├── exceptions.py # Custom exceptions
└── tools/ # Tool implementations
├── nodes.py
├── vms.py
├── containers.py
├── snapshots.py
├── storage.py
├── tasks.py
├── ssh.py
└── users.pyDevelopment
Install dev dependencies
pip install -e ".[dev]"Run tests
pytest -v --cov=proxmox_mcpLint and format
ruff check src/
ruff format src/Security Notes
Never commit
.env— It contains sensitive credentialsUse API tokens — Prefer tokens over user/password
Limit token permissions — Create dedicated tokens with minimal required permissions
Protected paths —
vm_file_writeblocks writes to sensitive files (/etc/shadow,/etc/passwd, etc.)
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
License
This project is licensed under the MIT License — see the LICENSE file for details.
Acknowledgments
Proxmox VE — Powerful open-source virtualization platform
Model Context Protocol — Anthropic's protocol for AI tool integration
Claude — AI assistant by Anthropic
Available Tools
37 toolsclone_vmA
Clone une VM ou un template QEMU. Crée une nouvelle VM à partir d'une VM source (template ou VM arrêtée). Supporte le choix du nœud cible et du stockage.
Inputs: node (required), vmid (required), newid (required), full, +4 more.
create_snapshotB
Crée un snapshot d'une VM ou conteneur
Inputs: name (required), node (required), type (required), vmid (required), +2 more.
create_userB
Crée un nouvel utilisateur Proxmox
Inputs: userid (required), email, enable, expire, +5 more.
delete_snapshotC
Supprime un snapshot d'une VM ou conteneur
Inputs: node (required), type (required), vmid (required), snapname (required).
delete_userA
Supprime un utilisateur Proxmox. ATTENTION: Action irréversible!
Inputs: userid (required).
destroy_vmA
DANGER: Supprime définitivement une VM QEMU ou conteneur LXC et ses disques. Action irréversible!
Inputs: node (required), vmid (required), type, purge.
fix_apt_reposB
Corrige les dépôts APT Proxmox pour les installations sans souscription. Désactive le dépôt enterprise et active le dépôt community no-subscription.
Inputs: node (required), disable_enterprise, enable_no_subscription.
get_container_detailsA
Récupère la configuration complète d'un conteneur LXC: CPU, RAM, disques, réseau, statut
Inputs: node (required), vmid (required).
get_node_statusA
Récupère les métriques détaillées d'un nœud Proxmox: CPU, RAM, disque, version PVE, kernel
Inputs: node (required).
get_storage_contentC
Liste le contenu d'un pool de stockage (images, ISOs, backups, etc.)
Inputs: node (required), storage (required), content_type.
get_task_statusA
Récupère le statut détaillé d'une tâche Proxmox
Inputs: node (required), upid (required).
get_userB
Récupère les détails d'un utilisateur Proxmox
Inputs: userid (required).
get_vm_detailsB
Récupère la configuration complète d'une VM QEMU: CPU, RAM, disques, réseau, statut
Inputs: node (required), vmid (required).
list_containersA
Liste tous les conteneurs LXC du cluster ou d'un nœud spécifique
Inputs: node.
list_nodesA
Liste tous les nœuds du cluster Proxmox avec leur statut, utilisation CPU/RAM/disque et uptime
Inputs: no named parameters.
list_snapshotsB
Liste les snapshots d'une VM ou conteneur
Inputs: node (required), vmid (required), type.
list_storageA
Liste les pools de stockage d'un nœud avec utilisation
Inputs: node (required).
list_tasksB
Liste les tâches récentes d'un nœud Proxmox
Inputs: node (required), vmid, limit.
list_usersA
Liste tous les utilisateurs Proxmox
Inputs: no named parameters.
list_vmsA
Liste toutes les VMs QEMU du cluster ou d'un nœud spécifique
Inputs: node.
pct_execA
Exécute une commande shell dans un conteneur LXC via pct exec. Équivalent de 'pct exec -- '. Nécessite SSH. Supporte les commandes complexes avec pipes, redirections, etc.
Inputs: node (required), vmid (required), command (required), timeout.
reboot_vmB
Redémarre une VM QEMU ou conteneur LXC
Inputs: node (required), vmid (required), type.
rollback_snapshotA
Restaure une VM ou conteneur vers un snapshot. ATTENTION: L'état actuel non sauvegardé sera perdu!
Inputs: node (required), type (required), vmid (required), snapname (required).
set_container_configB
Modifie la configuration d'un conteneur LXC (CPU, RAM, swap, hostname, etc.)
Inputs: node (required), vmid (required), swap, cores, +6 more.
set_vm_configB
Modifie la configuration d'une VM QEMU (CPU, RAM, nom, etc.)
Inputs: node (required), vmid (required), name, cores, +7 more.
shutdown_vmB
Arrête proprement une VM QEMU ou conteneur LXC via ACPI/signal shutdown
Inputs: node (required), vmid (required), type.
ssh_executeB
Exécute une commande SSH sur un nœud Proxmox. Permet d'administrer directement le système hôte.
Inputs: node (required), command (required), timeout.
ssh_read_fileB
Lit le contenu d'un fichier sur un nœud Proxmox via SSH
Inputs: node (required), path (required), max_size.
ssh_write_fileA
Écrit un fichier sur un nœud Proxmox via SSH. Crée automatiquement un backup du fichier existant.
Inputs: node (required), path (required), content (required), mode, +1 more.
start_vmB
Démarre une VM QEMU ou un conteneur LXC
Inputs: node (required), vmid (required), type.
stop_vmA
Arrête de force une VM QEMU ou un conteneur LXC (équivalent à couper l'alimentation)
Inputs: node (required), vmid (required), type.
update_userB
Modifie un utilisateur Proxmox existant
Inputs: userid (required), email, enable, groups, +4 more.
vm_execA
Exécute une commande dans une VM via le QEMU Guest Agent. Retourne un PID à utiliser avec vm_exec_status pour obtenir le résultat.
Inputs: node (required), vmid (required), command (required).
vm_exec_statusB
Récupère le résultat d'une commande exécutée via guest agent (stdout, stderr, exit code)
Inputs: pid (required), node (required), vmid (required).
vm_exec_syncC
Exécute une commande shell dans une VM et retourne le résultat directement. Supporte les commandes complexes avec arguments, pipes, etc. Nécessite SSH.
Inputs: node (required), vmid (required), command (required), timeout.
vm_file_readC
Lit un fichier dans une VM via le QEMU Guest Agent
Inputs: node (required), path (required), vmid (required).
vm_file_writeA
Écrit un fichier dans une VM via le QEMU Guest Agent. Certains chemins système (/etc/shadow, /etc/passwd, etc.) sont protégés.
Inputs: node (required), path (required), vmid (required), content (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Most tools target distinct resources or actions, but the multiple exec functions (pct_exec, vm_exec, vm_exec_sync, ssh_execute) could cause confusion despite clear descriptions. Overall clear boundaries are maintained.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_vms, create_user, get_vm_details). The few exceptions like pct_exec are standard Proxmox conventions and don't break consistency.
With 37 tools, the server is extensive but well-justified for covering VMs, containers, nodes, storage, users, and system maintenance. It's on the higher end but still scoped to Proxmox administration.
Covers most CRUD operations for VMs and containers, users, and snapshots, but lacks a create_vm tool (only clone is available) and backup/restore functionality. Notable gaps for basic VM provisioning.
Maintenance
Related MCP Connectors
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Manage Rackspace Spot Kubernetes Cloudspaces, node pools, and VMs from your AI assistant.
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Manage American Cloud VMs, Kubernetes, databases, storage, networks and DNS from your AI assistant.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides tools to manage Proxmox VE clusters via Claude Code, enabling listing nodes, VMs, templates, power actions, and creation of LXC containers and VMs through the Proxmox REST API.1076 npm-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, and cluster operations via natural language.MIT
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE environments, including VMs, containers, storage, and cluster operations through natural language.7653 npmMIT
- AlicenseBqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, network, high availability, replication, SDN, and node administration.10017 npmMIT