Homelab MCP Server

Serveur MCP extensible pour gérer votre homelab directement depuis Claude AI. Contrôlez vos VMs, snapshots, services et fichiers en langage naturel.

Proxmox VE est entièrement supporté · VMware, Docker et d'autres plateformes sont prévus.

---

⚡ Installation en 3 étapes

1. Téléchargez le docker-compose.yml

curl -O https://raw.githubusercontent.com/faton5/homelab-mcp-server/master/docker-compose.yml

2. Remplissez vos 4 valeurs

Ouvrez docker-compose.yml et modifiez uniquement les lignes marquées ✏️ :

- PROXMOX_HOST=192.168.1.10          # ✏️ IP de votre Proxmox
- PROXMOX_PORT=8006                   # ✏️ Port (8006 par défaut)
- PROXMOX_TOKEN_ID=root@pam!mcp       # ✏️ Token ID
- PROXMOX_TOKEN_SECRET=xxxx-xxxx      # ✏️ Secret du token

Créer un token Proxmox : Datacenter → API Tokens → Add

3. Lancez le serveur

docker compose up -d

L'image est téléchargée automatiquement depuis GitHub Container Registry. ✅

---

🔌 Connecter Claude

Ajoutez ceci à votre config Claude Desktop (~/.config/claude/claude_desktop_config.json) :

{
  "mcpServers": {
    "homelab": {
      "url": "http://VOTRE_IP_DOCKER:10850/sse"
    }
  }
}

Remplacez VOTRE_IP_DOCKER par l'IP du serveur qui fait tourner Docker, puis redémarrez Claude (Ctrl+R).

<details> <summary>Autres clients MCP (Claude Code, Codeium, Gemini…)</summary>

Claude Code

claude mcp add homelab http://VOTRE_IP_DOCKER:10850/sse

Codeium / Gemini / autres

URL SSE : http://VOTRE_IP_DOCKER:10850/sse

</details>

---

🛠️ Outils disponibles (32)

Catégorie	Outils
VMs & Conteneurs	list_vms, list_nodes, list_servers, get_vm_status, start_vm, stop_vm⚠️, restart_vm⚠️
Gestion VMs	create_vm, clone_vm, delete_vm⚠️, modify_vm_config
Snapshots	create_snapshot, list_snapshots, restore_snapshot, delete_snapshot⚠️
Backups	list_backups, create_backup
Stockage & Disques	list_storage, add_disk, remove_disk⚠️, resize_disk
Migration	migrate_vm⚠️
Système	execute_command, get_system_info, check_updates, install_updates⚠️
Services	manage_service, list_services
Fichiers	read_file, write_file⚠️
Processus	list_processes, kill_process⚠️

⚠️ = demande une confirmation explicite avant exécution

---

💬 Exemples d'utilisation

"Liste toutes mes VMs Proxmox"
"Quel est le statut de HLB-VPN-01 ?"
"Crée un snapshot de HLB-NAS-01 nommé avant-migration"
"Augmente la RAM de HLB-DOCKER-01 à 8 Go"
"Montre les 20 processus qui consomment le plus de RAM sur HLB-NC-01"
"Redémarre le service nginx sur HLB-HA-01"
"Liste les backups disponibles sur le node PROXMOX"

---

🔍 Dépannage

VMs non détectées → Vérifiez l'IP Proxmox et les permissions du token API.

Exécution de commandes impossible → Installez qemu-guest-agent dans vos VMs.

MCP non visible dans Claude → Vérifiez que le container tourne (docker ps), puis redémarrez Claude (Ctrl+R).

Logs du serveur :

docker logs infra-manager-mcp

---

🤝 Contribuer

Pull requests et issues bienvenus ! Priorités : support VMware, Docker, équipements réseau.

📄 Licence

MIT — voir LICENSE

---

Built with MCP · Powered by proxmoxer · For Claude AI