Chiedi una card.
Compare.

Cosa serve

Un assistente con MCP locale

Claude Desktop, Claude Code, Codex (CLI, app o estensione per l’editor) oppure Gemini CLI. Dal solo browser (claude.ai, ChatGPT) non funziona: serve un programma che giri sul tuo computer per parlare con la tua casa.

Node 20 o successivo

Sullo stesso computer. Niente da clonare o compilare: il server MCP si scarica da solo.

La rete di casa

Quel computer deve raggiungere il tuo Home Assistant.

1. Apri la porta (una volta sola)

In Home Assistant: Impostazioni → Applicazioni → Oikos → Rete. Alla voce 3565/tcp scrivi 3565 e salva.

Normalmente Oikos non pubblica porte: il pannello passa da Home Assistant, che autentica lui. Un programma esterno quella strada non la può usare e ha bisogno di una porta sua. Sulla porta c’è qualcosa in ascolto solo mentre il canale è acceso, e risponde solo agli indirizzi dello sviluppo card (più le funzioni da amministratore che attivi tu), solo con il token.

2. Accendi il canale

In Oikos: menu ⋮ → MCP. Scegli quanto deve restare aperto: 30 minuti, 1 ora, 2 ore, 8 ore o senza scadenza. Se ti servono, spunta le funzioni da amministratore. Premi Accendi e copia il token.

3. Collega l’assistente

Nella pagina ⋮ → MCP trovi la configurazione già pronta, con indirizzo e token dentro, e un pulsante per copiarla. Ecco dove va per ogni assistente.

Claude Desktop

Impostazioni → Sviluppatore → Modifica configurazione (claude_desktop_config.json). Incolla, salva e riavvia Claude.

{
  "mcpServers": {
    "oikos": {
      "command": "npx",
      "args": ["-y", "oikos-mcp"],
      "env": {
        "OIKOS_URL": "http://homeassistant.local:3565",
        "OIKOS_TOKEN": "il-token-copiato"
      }
    }
  }
}

Claude Code

Esegui nel terminale, poi riavvia Claude Code:

claude mcp add oikos --scope user \
  -e OIKOS_URL=http://homeassistant.local:3565 \
  -e OIKOS_TOKEN=il-token-copiato \
  -- npx -y oikos-mcp

Codex

Vale per Codex CLI, app ed estensione per l’editor. Aggiungi in ~/.codex/config.toml, poi riavvia Codex:

[mcp_servers.oikos]
command = "npx"
args = ["-y", "oikos-mcp"]
env = { OIKOS_URL = "http://homeassistant.local:3565", OIKOS_TOKEN = "il-token-copiato" }

Gemini CLI

In ~/.gemini/settings.json lo stesso blocco mcpServers di Claude Desktop (se il file esiste già, unisci la voce), poi riavvia Gemini CLI.

OIKOS_URL è l’indirizzo locale di Home Assistant con la porta 3565, non quello di Nabu Casa o del tuo dominio: vale anche se di solito apri Home Assistant da fuori casa.

4. Chiedi

«Fammi una card che mostra quanto consuma il frigo oggi»

L’assistente cerca le tue entità, scrive la card, la installa e chiede al pannello di ricaricarsi.

«Una card con la temperatura di tutte le stanze, dalla più calda»

Se qualcosa non va, rilegge l’errore del pannello e corregge da solo.

«Quanto ho prodotto col fotovoltaico questo mese? Fammici una card»

La card resta tua: la trovi installata e la modifichi come le altre.

Scadenza e revoca

Con una durata

Alla scadenza il canale si chiude da solo e l’assistente ti dirà che l’accesso è rifiutato. Riaccendi da ⋮ → MCP, aggiorna OIKOS_TOKEN con quello nuovo e riavvia l’assistente.

Senza scadenza

Il token resta valido anche dopo i riavvii di Oikos e di Home Assistant, finché non premi Revoca. La pagina mostra quando è stato usato l’ultima volta.

Funzioni da amministratore (facoltative)

Prima di premere Accendi puoi spuntare alcune funzioni da amministratore di Home Assistant. Di fabbrica sono tutte spente, valgono solo per quella sessione e ogni uso finisce in un registro, nella pagina MCP e in /config/oikos-admin-audit.log. Per cambiarle: spegni e riaccendi, esce un token nuovo.

Statistiche

Cerca e legge le statistiche a lungo termine, corregge un salto nella somma (il classico contatore che impazzisce), cancella una statistica.

Log

Legge avvisi ed errori di Home Assistant, come in Impostazioni → Sistema → Log, filtrabili per parola.

Riavvio

Riavvia Home Assistant, dopo aver controllato la configurazione.

Le operazioni che cambiano qualcosa (correggere o cancellare statistiche, riavviare) richiedono la tua conferma esplicita: l’assistente deve chiederti il sì, e senza quella conferma Oikos le rifiuta. Attiva solo quello che ti serve in quel momento.

Cosa può fare, e cosa no

Il token vale solo per lo sviluppo card e per le funzioni da amministratore che hai attivato: non è la tua chiave di licenza e non è il token di Home Assistant.

Se non funziona