MCP in Home Assistant: Collegare Claude e ChatGPT alla tua casa

SINTESI:

Da Home Assistant 2026.10 il server MCP si attiva con un clic da Impostazioni → Sistema → AI. La parte difficile non è attivarlo: è renderlo raggiungibile. Claude e ChatGPT si collegano dal loro cloud, quindi Home Assistant deve essere raggiungibile da internet in HTTPS con un certificato valido. Una VPN come Tailscale da sola non basta. La seconda decisione importante è cosa esporre: si parte da Device control in sola lettura e si allarga solo se serve.

Nota di accompagnamento al video sul canale @alessandrosimonitto. Scritta su Home Assistant 2026.11. I nomi delle opzioni sono quelli della documentazione ufficiale in inglese: nell’interfaccia italiana la traduzione può cambiare.

---

COS’È MCP IN 30 SECONDI

Model Context Protocol è uno standard aperto con cui un’applicazione AI scopre e usa i tool messi a disposizione da altri programmi. Home Assistant fa da server MCP: espone come tool le stesse API per LLM che usa Assist quando gli colleghi un agente conversazionale. Il client AI legge l’elenco dei tool e decide da solo quando chiamarli.

flowchart LR
    A[Claude / ChatGPT] -->|HTTPS + OAuth| B[Server MCP di Home Assistant]
    B --> C[Device control: entità esposte ad Assist]
    B --> D[Home Assistant: log, storico, azioni]
    C --> E[Dispositivi]
    D --> E

---

SERVER O CLIENT: DUE DIREZIONI DIVERSE

In Home Assistant ci sono due integrazioni con nomi quasi uguali:

Integrazione	Direzione	A cosa serve
Model Context Protocol Server (mcp_server)	AI esterna → Home Assistant	Claude, ChatGPT o Claude Code leggono e controllano la casa
Model Context Protocol (mcp)	Home Assistant → server MCP esterno	L’agente conversazionale di Assist usa tool di altri servizi

Questa guida parla della prima. La seconda è utile quando vuoi dare ad Assist capacità che non ha di suo; da 2026.10 riconosce in automatico le app che espongono un proprio server MCP.

---

PREREQUISITI

• Home Assistant 2026.10 o successivo per la card one click. L’integrazione esiste da 2025.2, ma prima andava configurata a mano.
• Un account amministratore per la configurazione. Per l’uso quotidiano meglio un utente dedicato all’AI (vedi sicurezza).
• Accesso remoto HTTPS con certificato valido, se usi client cloud come claude.ai, Claude Desktop o ChatGPT.
• External URL corretto in Impostazioni → Sistema → Rete.
• Le entità che vuoi far usare all’AI esposte in Impostazioni → Assistenti vocali → Esponi.

---

IL NODO DELL’ACCESSO REMOTO

È qui che si blocca quasi tutti. Il motivo è semplice: con i custom connector, Claude raggiunge il server MCP dai server di Anthropic, anche quando usi Claude Desktop. Lo stesso vale per ChatGPT. Quindi:

• un indirizzo locale (http://homeassistant.local:8123) non funziona;
• scrivere https:// davanti a quell’indirizzo non cambia nulla: HTTPS lo deve servire qualcuno;
• un certificato self-signed o una CA casalinga non bastano, perché i server di Anthropic non si fidano della tua CA;
• la tua VPN non c’entra: i server di Anthropic non sono nella tua rete privata.

Le strade possibili

Metodo	Pro	Contro
Home Assistant Cloud (Nabu Casa)	Il più semplice: hostname e certificato li gestisce lui, nessuna porta aperta. Sostieni lo sviluppo di Home Assistant	Abbonamento a pagamento
Cloudflare Tunnel (app Cloudflared)	Gratuito, nessuna porta aperta	Serve un dominio su Cloudflare. Le regole anti bot e WAF possono bloccare i client AI (vedi troubleshooting)
Tailscale Funnel (app Tailscale)	Gratuito, nessuna porta aperta, certificato valido su *.ts.net rinnovato in automatico	Funnel è in beta e ha limiti di banda; la pagina di login diventa pubblica
Reverse proxy (NGINX + Let’s Encrypt)	Gratuito, controllo totale	Devi aprire la porta 443 sul router e gestire DNS e certificati
SSL nativo (ssl_certificate nel blocco http:)	Nessun componente aggiuntivo	Sconsigliato: tutta l’istanza diventa solo HTTPS e l’accesso locale in http smette di funzionare

Qualunque strada scegli, l’URL che dai al client deve coincidere esattamente con l’Internal URL o l’External URL configurato in Impostazioni → Sistema → Rete. Se non coincide, il login OAuth fallisce in modi poco chiari.

Se usi già Tailscale

Se oggi ti colleghi a Home Assistant in http dentro la tailnet, è normale: il traffico è già cifrato da Tailscale. Ma Claude non è nella tua tailnet. Tailscale offre due modalità con certificato valido:

	Tailscale Serve	Tailscale Funnel
Chi raggiunge Home Assistant	Solo i dispositivi della tua tailnet	Chiunque da internet
Connettore su claude.ai, Desktop e mobile	No	Sì
Claude Code su un PC nella tailnet	Sì	Sì

Se ti basta Claude Code sui tuoi computer, Serve è la scelta migliore: HTTPS valido e niente di pubblico. Per i connettori di Claude e ChatGPT serve Funnel. La stessa Tailscale sconsiglia Funnel se non ti serve davvero, perché mette Home Assistant su internet: non è peggio di Nabu Casa o di un reverse proxy, ma va fatto sapendo cosa si sta aprendo.

Tailscale Funnel passo per passo

1. Nella console di amministrazione Tailscale verifica che siano attivi MagicDNS, i certificati HTTPS e l’attributo funnel nei nodeAttrs della policy (di default vale per autogroup:member).
2. In Home Assistant vai in Impostazioni → Sistema → Rete → HTTP server, attiva Trust X-Forwarded-For e aggiungi 127.0.0.1 tra i trusted proxies. Dalla 2026.8 si fa da interfaccia; sulle versioni precedenti va nel blocco http: di configuration.yaml.
3. Nell’app Tailscale imposta share_homeassistant: funnel e share_on_port: 443, poi riavvia l’app.
4. Nella console Tailscale, in Machines, disattiva la scadenza della chiave (Disable key expiry) della macchina di Home Assistant. Altrimenti, alla scadenza, il nodo si scollega e il connettore smette di funzionare.
5. In Impostazioni → Sistema → Rete imposta l’External URL a https://homeassistant.<tua-tailnet>.ts.net, senza porta.
6. Prova dal telefono in rete mobile con Tailscale spento. Un URL appena creato può impiegare qualche minuto a risolversi.

Verifica prima di collegare il client

curl https://<tuo-host>/.well-known/oauth-authorization-server

Deve rispondere un JSON con URL completi in https (issuer, endpoint di autorizzazione e token). Se vedi percorsi relativi, il problema è l’hostname o il proxy, non il client AI.

---

ATTIVARE IL SERVER MCP

1. Vai in Impostazioni → Sistema → AI.
2. Sulla card Model Context Protocol premi Enable.
3. Copia l’URL con l’icona accanto:
   • Main URL: https://<tuo-host>/api/mcp, quello consigliato;
   • gli URL individuali dei singoli set di tool, per esempio https://<tuo-host>/api/mcp/assist.
4. Dietro le quinte viene creata l’integrazione Model Context Protocol Server. Le opzioni si cambiano da Impostazioni → Dispositivi e servizi → Model Context Protocol → Configura.

Se la card ti mostra un indirizzo in http, non è un’impostazione da cambiare sul connettore: costruisci l’URL con il tuo host HTTPS pubblico e lo stesso percorso /api/mcp.

---

SCEGLIERE COSA ESPORRE

È la decisione più importante, perché stabilisce cosa può fare l’AI in casa tua.

I set di tool

Set	Cosa può fare	Account richiesto
Device control	Legge e controlla solo le entità esposte ad Assist	Anche non amministratore
Home Assistant	Legge tutte le entità, i log, lo storico e le statistiche; cerca e chiama qualsiasi azione; elenca e ricarica le integrazioni	Sempre amministratore

Il set Home Assistant è stato potenziato in 2026.11 per il troubleshooting: l’AI può leggere il System Log e lo storico per aiutarti a capire cosa non va. Il rovescio della medaglia è che può anche agire sul sistema, non solo osservarlo.

Altre integrazioni possono aggiungere i loro set di tool: per esempio KNX da 2026.10.

Le opzioni del Main URL

Opzione	Default	Effetto
Expose all AI tools	On	Espone tutti i set, compresi quelli che arriveranno in futuro con altre integrazioni
AI tools	Attiva solo se l’opzione sopra è Off	Scelta manuale dei set da esporre
Require an administrator account	On	Solo account amministratore possono collegarsi
Read-only	Off	Limita il Main URL ai tool che non modificano nulla

URL INDIVIDUALI:

Gli URL individuali ignorano le opzioni sopra, non sono mai in sola lettura e, tranne Device control, richiedono sempre un account amministratore.

INSTALLAZIONI GIÀ ESISTENTI:

Se avevi configurato l’integrazione prima della 2026.10, Expose all AI tools e Require an administrator account restano disattivate, per non rompere i client che già usavi.

---

COLLEGARE CLAUDE (WEB, DESKTOP, MOBILE)

1. Su claude.ai apri la pagina dei connettori e scegli Add → Add custom connector. In Claude Desktop: Settings → Connectors → Add → Add custom connector.
2. Name: Home Assistant. MCP Server URL: il tuo Main URL in HTTPS.
3. Premi Add. Nella finestra che compare scegli:
   • Authentication: Sign in now
   • OAuth client: Use Claude’s published identity
4. Premi Add, poi Connect, e fai il login su Home Assistant.

Il connettore configurato sul web compare anche nell’app desktop e nelle app mobile. Prima di ogni chiamata a un tool, Claude chiede il permesso: è il momento giusto per guardare cosa sta per fare.

La disponibilità dei connettori custom può dipendere dal piano del tuo account: controlla le condizioni attuali prima di partire.

---

COLLEGARE CLAUDE CODE

claude mcp add --transport http home-assistant https://<tuo-host>/api/mcp
claude mcp login home-assistant

Il secondo comando apre il browser per il login su Home Assistant. Claude Code gira sul tuo computer ma accetta solo URL in HTTPS: se usi Tailscale, basta Serve con l’External URL impostato sul nome *.ts.net, senza esporre nulla su internet.

---

ALTERNATIVA SOLO LAN: CLAUDE DESKTOP CON MCP-PROXY

Per chi non vuole esporre Home Assistant su internet e usa solo Claude Desktop. Invece del connettore cloud, Claude Desktop avvia un piccolo processo locale (stdio) che fa da ponte verso /api/mcp usando un long-lived access token.

1. Crea il token in Profilo → Sicurezza → Token di accesso a lunga durata. Viene mostrato una sola volta.
2. Installa uv sul computer con Claude Desktop.
3. In Claude Desktop apri Settings → Developer → Edit Config e aggiungi:

{
  "mcpServers": {
    "Home Assistant": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "-H",
        "Authorization",
        "Bearer <token>",
        "http://<ip-home-assistant>:8123/api/mcp"
      ]
    }
  }
}

4. Chiudi e riapri Claude Desktop.

METODO DELLA COMMUNITY:

La pagina ufficiale dell’integrazione oggi documenta solo il collegamento con OAuth. Questa configurazione viene da guide della community: funziona perché Home Assistant accetta il token come header Authorization: Bearer, ma tieni presente che il token ha gli stessi permessi dell’utente che l’ha creato.

---

ALTRI CLIENT

Client	Come si aggiunge
ChatGPT	chatgpt.com/plugins → Add → Add custom MCP server, Authentication OAuth, poi Create as plugin
Codex	codex mcp add homeassistant --url <url>
OpenCode	opencode mcp add home-assistant --url <url> e poi opencode mcp auth home-assistant

Anche qui le funzioni disponibili, in particolare le azioni di scrittura, possono dipendere dal piano dell’account.

---

SICUREZZA

DA SAPERE PRIMA DI COLLEGARE UN'AI:

• Il set Home Assistant può chiamare qualsiasi azione. Su Home Assistant OS questo comprende anche spegnere l’host.
• Un modello linguistico può sbagliare entità o seguire istruzioni nascoste in un testo che legge (prompt injection). Serrature, allarmi e cancelli non si espongono senza un motivo preciso.
• Le automazioni scritte dall’AI vanno sempre rilette, soprattutto su riscaldamento e sicurezza.

La configurazione con cui partirei:

1. Utente dedicato all’AI, non il tuo account personale.
2. Solo Device control, con Expose all AI tools disattivato.
3. Read-only attivo per i primi giorni.
4. Entità esposte ridotte al minimo indispensabile.
5. Autenticazione a due fattori su tutti gli utenti e IP ban attivo, soprattutto se usi Funnel o un reverse proxy.
6. L’accesso si revoca in qualsiasi momento: scollegando il connettore dal client oppure eliminando il token di aggiornamento in Profilo → Sicurezza.

Per l’esposizione sicura in generale vedi anche 14 Utenti auth ed esposizione sicura.

---

COSA CHIEDERE ALL’AI: ESEMPI

• Con Device control: “Quali luci sono accese in casa?”, poi “Spegni le luci del soggiorno”.
• Con il set Home Assistant: “Controlla il log degli errori delle ultime 24 ore e dimmi cosa non va”.
• Con lo storico: “Quanto ha consumato la lavatrice la settimana scorsa?”
• Prova di sicurezza: chiedi di agire su un’entità che non hai esposto e verifica che venga rifiutata.

---

TROUBLESHOOTING

Sintomo	Causa probabile	Cosa fare
Il login OAuth fallisce in loop	URL diverso da Internal URL o External URL	Allinea Impostazioni → Sistema → Rete all’URL usato nel client
Il client chiede un client ID a mano	Client ID sbagliato	Usa l’URL base del client (per esempio https://claude.ai), mai quello di Home Assistant. Il client secret non serve: se il campo è obbligatorio, scrivi un testo qualsiasi
La discovery OAuth fallisce dietro un proxy	Header X-Forwarded-Host o X-Forwarded-Proto mancanti o sbagliati	Configura i trusted proxies oppure usa Nabu Casa
Un client che richiede Dynamic Client Registration non si registra	Home Assistant usa il Client ID Metadata Document, non RFC 7591	Se il client lo permette, inserisci a mano gli endpoint OAuth
Dopo alcuni tentativi il collegamento viene rifiutato	IP bannato	Controlla ip_bans.yaml, rimuovi l’IP e riavvia
”No matching entities are exposed”	Entità non esposta ad Assist	Esponila in Impostazioni → Assistenti vocali → Esponi
”Unknown tool” dopo aver cambiato le opzioni	Il client ha in cache la vecchia lista di tool	Scollega e ricollega il connettore
Dal browser funziona, da Claude no	Cloudflare blocca il traffico AI: opzione Block AI Training Bots, regole WAF per paese, mTLS	Escludi il traffico dei client AI da quelle regole. Claude e ChatGPT si collegano dagli Stati Uniti

Per il debug, con Device control attivo Home Assistant espone anche la resource in sola lettura homeassistant://assist/context-snapshot, che contiene lo stesso testo restituito dal tool GetLiveContext: è il modo più rapido per vedere cosa “vede” l’AI della tua casa.

---

OLTRE IL SERVER UFFICIALE: HA-MCP

Esiste anche un server della community, ha-mcp (homeassistant-ai/ha-mcp), che fa molto di più del server ufficiale:

Funzione	Server ufficiale	ha-mcp
Controllo dispositivi e azioni	Sì	Sì
Storico e log	Sì (da 2026.11)	Sì
Creare e modificare automazioni e script	No	Sì
Dashboard	No	Sì
Debug delle automazioni dalle trace	No	Sì
Helper, aree, zone, registry	No	Sì

Richiede Home Assistant 2026.8 o successivo ed è disponibile come app (ex add-on) o come custom component. È un progetto della community, non testato né supportato dal progetto Home Assistant: più potere significa anche più attenzione a cosa gli lasci fare.

---

COLLEGAMENTI

• IA in Home Assistant
• 14 Utenti auth ed esposizione sicura
• Documentazione ufficiale: Model Context Protocol Server
• Release notes: Home Assistant 2026.10 e Home Assistant 2026.11
• Tailscale: Funnel e app Tailscale per Home Assistant
• ha-mcp

---

SPUNTI VIDEO COLLEGATI

• spunto: ha-mcp in pratica, far scrivere e correggere automazioni all’AI con backup prima di ogni modifica
• spunto: accesso remoto a confronto, Nabu Casa contro Cloudflare Tunnel contro Tailscale Funnel
• spunto: un utente dedicato all’AI con permessi minimi, configurato passo per passo

---

CHANGELOG

Data	Versione	Modifica	Note
2026-11-08	0.1	Prima stesura pubblica	Basata su Home Assistant 2026.11