Gestione di reti e telecamere UniFi con agenti LLM

Se hai mai configurato un firewall in UniFi Controller o cercato un clip specifico da una telecamera in UniFi Protect, sai come va. Apri l'interfaccia web, clicchi attraverso i menu, cerchi il VLAN o l'indirizzo MAC del client giusto. Automatizzare questi task con script è possibile, ma l'API di Ubiquiti è bizzarra in alcuni punti e cambia da versione a versione.

Il progetto unifi-mcp adotta un approccio diverso. È un insieme di server che utilizzano il Model Context Protocol (MCP) per connettere assistenti AI come Claude Code, Codex o OpenClaw ai controller UniFi.

Cosa c'è dentro il progetto

Il repository è strutturato come un monorepo Python e TypeScript. È diviso in tre moduli principali che coprono le aree di prodotto Ubiquiti:

1. Network — un modulo per gestire apparecchiature di rete. Dispone di 186 strumenti per lavorare con VLAN, firewall, client, reti Wi-Fi e dispositivi.
2. Protect — uno strumento di videosorveglianza. Include 61 funzioni per cercare eventi, analizzare rilevamenti di movimento e lavorare con le telecamere.
3. Access — gestione del controllo accessi. Contiene 36 funzioni per lavorare con porte, credenziali e log di accesso.

Inoltre, il progetto include un server REST/GraphQL separato per client che non supportano ancora il protocollo MCP, e un sistema Cloud Relay per connettere una rete locale con agenti remoti tramite Cloudflare Workers.

Sicurezza e protezione da errori fatali

Concedere a un modello linguistico accesso diretto al firewall della tua rete domestica o d'ufficio è una mossa audace. Gli sviluppatori di unifi-mcp hanno integrato due meccanismi di sicurezza per ridurre il rischio di rompere qualcosa.

Il primo meccanismo è il concetto di anteprima-poi-conferma. Qualsiasi modifica alla configurazione restituisce prima un'anteprima: l'agente AI mostra l'esatto JSON o l'elenco di regole che intende inviare al controller e attende la tua conferma esplicita.

Il secondo elemento è la redazione automatica dei dati sensibili. Per impostazione predefinita, tutte le password Wi-Fi, le chiavi VPN, le community SNMP e i token vengono rimossi dalle risposte degli strumenti e sostituiti con ***REDACTED***. Il modello non vedrà i segreti nel contesto e non potrà accidentalmente "perderli" nei log. Tuttavia, se stai eseguendo uno script di amministrazione locale fidato, puoi disabilitare il mascheramento tramite variabili d'ambiente.

Scenari pratici

invece di cercare manualmente attraverso l'interfaccia, puoi scrivere query all'agente in linguaggio naturale.

Per il modulo di rete:

• "Mostra tutti i client nel VLAN ospite, la loro intensità del segnale e il volume di traffico"
• "Controlla le regole del firewall, trova criteri duplicati e in conflitto"
• "Crea una regola che blocca l'accesso a internet per i dispositivi IoT da mezzanotte alle 6 del mattino"

Per i sistemi di sicurezza:

• "Trova tutti gli eventi di riconoscimento auto all'ingresso questa settimana"
• "Incrocia i timestamp: chi ha fatto il badge alla porta principale alle 2 del mattino e quale telecamera ha registrato movimento nelle vicinanze in quel momento"

A proposito, per i task frequenti il repository include già competenze integrate per gli agenti. Ad esempio, Firewall Auditor esegue 16 controlli di sicurezza di rete e restituisce un punteggio su una scala di 100 punti con raccomandazioni di correzione.

Come funziona tecnicamente

Il progetto utilizza attivamente le funzionalità delle recenti revisioni del protocollo MCP. Poiché uno strumento con 186 funzioni può riempire il contesto di un LLM prima ancora che la conversazione inizi, qui è implementata la scoperta pigra (lazy discovery). Inizialmente, il server passa solo i meta-strumenti di ricerca all'assistente, e gli endpoint specifici vengono caricati su richiesta.

L'avvio dei server in un ambiente locale viene eseguito con un singolo comando tramite uvx:

uvx unifi-network-mcp@latest
uvx unifi-protect-mcp@latest
uvx unifi-access-mcp@latest

La configurazione viene passata attraverso variabili d'ambiente. Avrai bisogno di un account amministratore locale sul controller UniFi per connetterti. Nota: gli account con autenticazione a due fattori o Ubiquiti SSO non funzioneranno — dovrai creare un utente di servizio locale separato affinché MCP funzioni.

Esempio di configurazione per Claude Desktop:

{
  "mcpServers": {
    "unifi-network": {
      "command": "uvx",
      "args": ["unifi-network-mcp@latest"],
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_USERNAME": "mcp-service-account",
        "UNIFI_PASSWORD": "your-safe-password"
      }
    }
  }
}

Vale la pena provarlo

Il progetto sembra maturo per la sua classe: 588 stelle su GitHub, commit attivi e supporto per Python 3.13+. Sarà utile per amministratori di sistema, appassionati di Home Assistant e chiunque costruisca automazione su Ubiquiti.

Se hai un solo punto di accesso a casa, c'è poco senso nell'impostare un server MCP. Ma per infrastrutture complesse con firewall, telecamere e controllo accessi, la possibilità di chiedere a un agente invece di cercare manualmente attraverso le dashboard fa risparmiare molto tempo.