Proxmox MCP : piloter ses VM et conteneurs LXC avec un agent IA

Proxmox VE expose une API REST complète pour administrer les machines virtuelles KVM et les conteneurs LXC d'un serveur dédié. Jusqu'ici, les administrateurs pilotaient cette API via des scripts shell en ligne de commande, des appels curl ou des outils comme Terraform et Ansible. Le Model Context Protocol (MCP) ouvre une autre approche : connecter un assistant IA (Claude Desktop, Claude Code, Cursor) directement à l'API Proxmox pour créer, démarrer, arrêter ou lister des machines virtuelles et des conteneurs en langage naturel, depuis le terminal ou l'éditeur de code. Pour les administrateurs de serveurs dédiés qui gèrent un environnement de virtualisation complet (cloud privé, cluster multi-noeuds), le gain de productivité est immédiat.

mcp-server-proxmox est un serveur MCP open source (licence MIT) qui traduit les appels de l'assistant IA en requêtes vers l'API Proxmox VE. Ce guide explique comment l'installer sur votre serveur, créer un token API Proxmox avec les permissions minimales nécessaires, configurer la connexion dans un client MCP compatible, et lancer vos premières commandes pour piloter votre infrastructure de virtualisation.

Le Model Context Protocol et Proxmox VE

Le MCP est un protocole ouvert, initié par Anthropic, qui standardise la communication entre un modèle de langage (LLM) et des sources de données ou des outils externes. Il repose sur le format JSON-RPC 2.0 et fonctionne avec deux transports : stdio (processus local) et HTTP streamable. Un serveur MCP expose des tools (fonctions appelables par le modèle), des resources (données consultables) et des prompts (modèles de requêtes prédéfinis).

Appliqué à Proxmox VE, le serveur MCP expose des outils qui correspondent aux endpoints de l'API Proxmox : lister les noeuds du cluster, afficher l'état d'une machine virtuelle, démarrer ou arrêter un conteneur LXC. L'assistant IA appelle ces outils en fonction de votre demande en langage naturel. Pas besoin de mémoriser les routes de l'API ni la syntaxe des requêtes HTTP : l'agent traduit "démarre la VM 101 sur le noeud pve1" en appel start_vm avec les bons paramètres.

Par rapport aux scripts d'automatisation classiques, le serveur MCP offre un avantage : l'administrateur n'écrit pas de script à l'avance. Il formule sa demande, le modèle choisit l'outil adapté et construit les paramètres. L'approche est complémentaire aux configurations Terraform ou Ansible, qui restent préférables pour les déploiements reproductibles et versionnés.

Prérequis

• Un serveur dédié ou VPS sous Proxmox VE 8.0 ou supérieur (testé jusqu'à Proxmox VE 9.2, version stable actuelle basée sur Debian 13 Trixie) ;
• Node.js 18.0 ou supérieur installé sur la machine qui exécutera le serveur MCP (votre poste local sous Ubuntu, Debian ou macOS, ou directement le serveur Proxmox) ;
• Un accès à l'interface web Proxmox (port 8006) pour créer le token API ;
• Un client MCP compatible : Claude Desktop, Claude Code, Cursor ou tout outil supportant le protocole MCP ;
• Git et les paquets npm installés sur la machine d'exécution pour cloner le dépôt et compiler le projet.

Créer un token API Proxmox avec les permissions minimales

Un token API Proxmox permet de s'authentifier auprès de l'API REST sans transmettre le mot de passe du compte utilisateur. Chaque token peut recevoir des permissions distinctes, indépendantes de celles du compte parent. Le principe du moindre privilège s'applique : le serveur MCP ne doit obtenir que les droits strictement nécessaires aux opérations qu'il exécute sur vos machines virtuelles et conteneurs.

Créer un utilisateur dédié

Créer un utilisateur distinct du compte root@pam permet de limiter la portée du token et de révoquer l'accès sans toucher aux autres comptes admin du serveur. Connectez-vous en SSH au noeud Proxmox et exécutez les commandes suivantes en ligne de commande :

pveum user add mcp@pve -comment "Token MCP server"
pveum passwd mcp@pve

Attribuer un rôle avec les permissions minimales

Créez un rôle personnalisé qui contient uniquement les privilèges utilisés par mcp-server-proxmox. Ces configurations de sécurité empêchent le serveur MCP de modifier le système d'exploitation hôte ou de supprimer des machines virtuelles :

pveum role add MCP-Operator -privs "VM.Audit,VM.PowerMgmt,Sys.Audit,Datastore.Audit"

Détail des privilèges :

Assignez ce rôle à l'utilisateur sur le chemin racine / (toutes les ressources du cluster) :

pveum aclmod / -user mcp@pve -role MCP-Operator

Générer le token API

Depuis l'interface web Proxmox, allez dans Datacenter > Permissions > API Tokens > Add. Sélectionnez l'utilisateur mcp@pve, donnez un nom au token (par exemple mcp-agent) et décochez la case "Privilege Separation". Avec la séparation de privilèges activée, le token n'a aucune permission par défaut et nécessite des ACL supplémentaires sur le token lui-même. En la désactivant, le token hérite des permissions de l'utilisateur parent, qui sont déjà limitées au rôle MCP-Operator.

Notez le Token ID (format mcp@pve!mcp-agent) et le Secret affiché une seule fois. Stockez-le dans un gestionnaire de mots de passe ou un fichier .env protégé (permissions 600).

Installer mcp-server-proxmox

Le serveur MCP se compile depuis les sources TypeScript. Sur la machine qui exécutera le serveur (votre poste local ou directement le serveur Proxmox), clonez le dépôt et installez les paquets nécessaires :

git clone https://github.com/heybearc/mcp-server-proxmox.git
cd mcp-server-proxmox
npm install
npm run build

La compilation produit le fichier dist/index.js, le point d'entrée du serveur MCP. Vérifiez que Node.js est bien en version 18 ou supérieure :

node --version

Sur un serveur Ubuntu ou Debian, si npm n'est pas installé, ajoutez les paquets depuis le gestionnaire de paquets du système d'exploitation ou utilisez NVM pour installer Node.js sans sudo :

sudo apt update && sudo apt install -y nodejs npm

Configurer la connexion au serveur Proxmox

Le serveur MCP utilise des variables d'environnement pour établir la connexion à l'API Proxmox. Créez un fichier .env dans le répertoire du projet :

PROXMOX_HOST=192.168.1.100
PROXMOX_PORT=8006
PROXMOX_USERNAME=mcp
PROXMOX_REALM=pve
PROXMOX_TOKEN=votre-secret-api-token
PROXMOX_TOKEN_NAME=mcp-agent
PROXMOX_VERIFY_SSL=false

PROXMOX_VERIFY_SSL=false est nécessaire si vous utilisez le certificat auto-signé installé par défaut par Proxmox VE. En production, remplacez-le par un certificat valide (Let's Encrypt ou certificat interne) et passez la variable à true. Pour sécuriser et mettre à jour votre installation Proxmox VE, consultez notre guide dédié.

Connecter un client MCP

Un client MCP est l'application qui communique avec le serveur MCP pour transmettre vos instructions au modèle IA. Voici la configuration pour Claude Desktop, applicable de manière similaire à Claude Code et Cursor.

Configuration pour Claude Desktop

Ouvrez le fichier de configuration de Claude Desktop (claude_desktop_config.json) et ajoutez le serveur :

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/chemin/vers/mcp-server-proxmox/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USERNAME": "mcp",
        "PROXMOX_TOKEN": "votre-secret-api-token",
        "PROXMOX_TOKEN_NAME": "mcp-agent"
      }
    }
  }
}

Remplacez /chemin/vers/ par le chemin absolu vers le répertoire cloné. Le transport utilisé est stdio : Claude Desktop lance le processus Node.js et communique avec lui via l'entrée et la sortie standard. Aucun port réseau n'est ouvert.

Configuration pour Claude Code

Dans Claude Code, ajoutez le serveur MCP via la commande /mcp add dans le terminal, en pointant vers le même fichier dist/index.js avec les variables d'environnement appropriées.

Outils MCP disponibles

Le serveur expose les outils suivants, que l'assistant IA peut appeler en réponse à vos demandes en langage naturel :

Avec ces outils, vous pouvez demander à l'agent des opérations comme "liste toutes les VM arrêtées sur le noeud pve1", "démarre le conteneur 205" ou "crée un conteneur LXC avec 2 coeurs, 4 Go de RAM et 20 Go d'espace disque".

Comparaison des méthodes d'administration Proxmox

Le serveur MCP n'est pas la seule manière de piloter les machines virtuelles et conteneurs Proxmox. Voici comment il se positionne face aux autres approches d'administration :

Le MCP convient aux opérations ponctuelles (inventaire, démarrage, arrêt, diagnostic). Pour le provisionnement à grande échelle ou les configurations versionnées dans Git, les administrateurs continueront à utiliser Terraform ou Ansible. Les deux approches coexistent sur le même environnement Proxmox.

Premières commandes en langage naturel

Une fois le serveur MCP connecté à votre client, testez les opérations de base. L'agent IA traduit vos instructions en appels aux outils MCP :

• "Quels noeuds sont dans mon cluster Proxmox ?" : appelle list_nodes, renvoie le nom, l'adresse IP, le statut et les ressources de chaque noeud.
• "Liste les VM sur pve1" : appelle list_vms avec le paramètre node=pve1, affiche le VMID, le nom, l'état (running/stopped) et les ressources allouées (processeur virtuel, mémoire).
• "Quel est le statut de la VM 101 ?" : appelle get_vm_status, renvoie la consommation processeur et mémoire, l'uptime, l'espace disque utilisé et la configuration réseau.
• "Démarre le conteneur 205 sur pve1" : appelle start_vm, le conteneur LXC passe à l'état running.
• "Arrête toutes les VM de test" : l'agent peut enchaîner list_vms puis stop_vm pour chaque machine virtuelle correspondant au filtre.
• "Quel noeud a le plus de RAM disponible ?" : appelle get_node_status sur chaque noeud et compare les processeurs et la mémoire libre pour vous recommander le meilleur emplacement.
• "Crée un conteneur LXC Ubuntu avec 2 coeurs et 4 Go de RAM" : appelle create_container avec un template Ubuntu et les ressources spécifiées (processeur, mémoire, espace disque).

Chaque appel passe par le token API avec les permissions du rôle MCP-Operator. L'agent ne peut exécuter que les opérations autorisées par les privilèges attribués. Si vous demandez une opération non couverte (par exemple créer un snapshot ou lancer une sauvegarde), l'API Proxmox refuse la requête et l'agent vous en informe.

Sécuriser l'accès MCP à Proxmox

Connecter un agent IA à l'API de votre hyperviseur mérite les mêmes précautions que tout accès automatisé à des environnements de virtualisation :

• Principe du moindre privilège : le rôle MCP-Operator créé plus haut ne contient que VM.Audit, VM.PowerMgmt, Sys.Audit et Datastore.Audit. Pas de VM.Allocate, pas de Sys.Modify, pas d'accès au stockage en écriture. Si vous n'avez pas besoin de create_container, retirez VM.PowerMgmt et gardez uniquement les privilèges d'audit (lecture seule).
• Token dédié, pas le compte root : ne connectez jamais le serveur MCP avec root@pam. Un token sur un utilisateur dédié se révoque en un clic sans affecter l'administration du serveur.
• Transport local (stdio) : le serveur MCP communique via stdin/stdout avec le client, sans ouvrir de port réseau. L'API Proxmox reste accessible uniquement via le port 8006, protégé par le pare-feu du serveur.
• TLS sur l'API Proxmox : remplacez le certificat auto-signé par un certificat valide et passez PROXMOX_VERIFY_SSL=true pour éviter les attaques man-in-the-middle entre le serveur MCP et l'API.
• Rotation du token : régénérez le token régulièrement (tous les 90 jours) et révoquez immédiatement tout token compromis depuis l'interface Proxmox.
• Accès SSH : si le serveur MCP tourne sur le noeud Proxmox, sécurisez l'accès SSH avec authentification par clé et désactivation du mot de passe.

Cas d'usage pour un serveur dédié

Sur un serveur dédié avec 40 coeurs et plusieurs dizaines de VM, piloter l'infrastructure en langage naturel prend tout son sens :

• Inventaire rapide : "combien de machines virtuelles tournent sur chaque noeud ?" remplace une série de requêtes API manuelles ou de scripts shell.
• Maintenance planifiée : "arrête toutes les VM sauf la 100 et la 101 sur pve1" avant une intervention matérielle sur les processeurs ou la mémoire du serveur.
• Provisionnement de conteneurs : "crée un conteneur LXC Debian avec 2 coeurs et 4 Go de RAM" simplifie le déploiement de services avec les scripts helper Proxmox VE.
• Diagnostic de ressources : "quel noeud a le plus de RAM libre ?" ou "quelles machines virtuelles utilisent plus de 90 % de leur espace disque ?" pour détecter les environnements sous-dimensionnés.
• Cloud privé : sur un cluster Proxmox utilisé comme cloud privé d'entreprise, l'agent permet aux administrateurs de vérifier l'état des environnements virtuels de chaque équipe sans naviguer dans l'interface web.
• Stockage : "quel est le taux d'utilisation du datastore NAS ?" pour surveiller l'espace disponible pour les sauvegardes et les images ISO des systèmes d'exploitation.

Le serveur MCP ne remplace pas un outil de monitoring dédié comme Grafana et Prometheus, mais il fournit un accès conversationnel pour les opérations ponctuelles sans quitter le terminal.

Limites actuelles

Le projet mcp-server-proxmox est en développement actif (v0.2.0). Quelques points à connaître avant de l'adopter dans votre environnement de production :

• Les opérations de snapshot, de migration à chaud et de clonage de machine virtuelle ne sont pas encore exposées comme outils MCP.
• La gestion des sauvegardes (backup Proxmox, planification de tâches de sauvegarde) n'est pas couverte par les outils actuels. Utilisez l'interface web ou la ligne de commande vzdump pour vos sauvegardes.
• Le package npm n'est pas encore publié : l'installation passe par le clonage du dépôt Git et la compilation des sources.
• La gestion du stockage (upload d'ISO, création de volumes) n'est pas couverte par les outils actuels.
• Le provisionnement avancé (intégration Netbox pour l'attribution IP, reverse proxy automatique) nécessite des configurations supplémentaires côté serveur Proxmox.

Le projet est sous licence MIT et ouvert aux contributions. Vérifiez les mises à jour du dépôt pour suivre l'ajout de nouveaux outils.

Conclusion

Le serveur MCP pour Proxmox VE transforme un assistant IA en interface d'administration pour vos machines virtuelles et conteneurs LXC. Avec un token API limité au strict nécessaire et un transport local sans port réseau exposé, l'intégration reste sécurisée. Les administrateurs de serveurs dédiés y trouveront un complément efficace aux scripts et à la ligne de commande pour les opérations de diagnostic, d'inventaire et de gestion courante de leurs environnements virtuels. Pour aller plus loin avec Proxmox VE sur un serveur dédié, consultez nos guides pour migrer de Proxmox VE 8 vers 9, installer pfSense en VM ou comparer Proxmox VE et OpenStack.