HomeLab MCP Server

Eigen MCP-server om je UniFi-netwerk te beheren via Claude. Proxmox en Home Assistant volgen later als apart uitbreidingsproject. Draait als Docker container (via Portainer) en is alleen bereikbaar binnen je eigen netwerk/VPN.

Zie INSTALLATIE.md voor de volledige stap-voor-stap gids afgestemd op jouw Portainer-omgeving.

1. Server draaien via Portainer

1. Kopieer deze map naar je Docker-host.

2. Maak in Portainer een nieuwe stack aan met docker-compose.yml, en vul de UniFi-variabelen in via het Environment variables-veld van het stack-formulier (geen los .env bestand nodig).

3. Deploy de stack.

Wil je lokaal testen buiten Portainer? Kopieer dan .env.example naar .env en draai:

docker compose up -d --build

4. Controleer of hij draait:

   docker compose logs -f

   Je moet zien: Uvicorn running on http://0.0.0.0:8000

De server is nu bereikbaar op http://<proxmox-ip>:8000/mcp binnen je LAN/VPN. Zet deze poort nooit publiek open op internet — dit is puur bedoeld voor gebruik binnen je eigen netwerk of via VPN (bv. WireGuard/Tailscale).

Related MCP server: unifi-mcp

2. Verbinden vanuit Claude Code (eenvoudigst)

claude mcp add --transport http homelab http://<proxmox-ip>:8000/mcp

Test daarna met bijvoorbeeld:

"Welke VM's draaien er op mijn Proxmox node?"

3. Verbinden vanuit Claude Desktop

Claude Desktop verwacht lokale (stdio) servers in zijn configuratiebestand. Voor een remote server zoals deze gebruik je de mcp-remote bridge.

Open je claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/config.json

• Windows: %APPDATA%\Claude\config.json

En voeg toe:

{
  "mcpServers": {
    "homelab": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://<proxmox-ip>:8000/mcp"]
    }
  }
}

Herstart Claude Desktop. Je zou dan de tools van deze server moeten zien verschijnen (bijv. ha_list_entities, pm_vm_action, uf_client_action).

4. Beschikbare tools

Alle uf_list_*-tools ondersteunen paginering: standaard worden alle pagina's opgehaald (fetch_all=true); met fetch_all=false plus offset/limit (max 200) haal je één pagina op. De UniFi-API geeft zelf maar 25 items per aanroep. | Pi-hole | pi_list_hosts | Geconfigureerde Pi-holes (alleen lezen) | | Pi-hole | pi_summary | Samenvatting + versies per Pi-hole | | Pi-hole | pi_top_clients | Topclients (alleen lezen) | | Pi-hole | pi_queries | Query log, filter op client/domein/tijd | | Home Assistant | ha_list_entities | Entiteiten zoeken (alleen lezen) | | Home Assistant | ha_get_state | Status van één entiteit (alleen lezen) | | Home Assistant | ha_statistic_ids | Beschikbare statistieken (kWh-tellers e.d.) | | Home Assistant | ha_statistics | Uur-/dag-statistieken ophalen (alleen lezen) |

De Home Assistant-tools lezen alleen. Ze hebben HA_URL en HA_TOKEN nodig in de omgeving van de container. Proxmox-tools staan gepland als los uitbreidingsproject.

5. Uitbreiden

Voeg een nieuw bestand toe in tools/, importeer mcp uit app.py, en gebruik @mcp.tool boven een functie. Voeg de import toe in server.py zodat de tool geregistreerd wordt bij het opstarten.

Veiligheidsopmerkingen

• De API-tokens in .env geven aanzienlijke controle over je infrastructuur (VM's stoppen, firewall/clients blokkeren, Home Assistant-apparaten aansturen). Behandel .env als een wachtwoordbestand.

• Begin met testen via read-only tools (*_list_*, *_get_*) voordat je Claude actiematige tools laat gebruiken (pm_vm_action, uf_client_action, ha_call_service).

• Overweeg een Proxmox API-token met beperkte rechten (niet root) aan te maken, specifiek voor deze server.