SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor

Claude aan Home Assistant koppelen met MCP: twee routes

De ingebouwde MCP Server of het communityproject ha-mcp: wat Claude in je huis mag lezen en schakelen, hoe Home Assistant bereikbaar wordt en waarom poort 8123 dicht blijft.

Claude koppelen aan Home Assistant met MCP: de korte versie

Je koppelt Claude aan Home Assistant met MCP (Model Context Protocol) via een van twee routes. De eerste is de ingebouwde integratie Model Context Protocol Server. De tweede is het communityproject ha-mcp. De ingebouwde integratie geeft standaard alle tools vrij. Beperk haar daarom eerst tot Device control. Daarna kies je hoe Claude je Home Assistant bereikt. De remote connectors in Claude.ai en Claude Desktop verbinden namelijk vanuit de cloud van Anthropic en niet vanaf je eigen pc.

Die laatste zin bepaalt de rest van je opzet. Een Home Assistant die alleen in je eigen netwerk of in je tailnet bestaat, is voor zo'n remote connector onbereikbaar. Lees daarom eerst wat elke route kan aanraken. Pas daarna kies je hoe je Home Assistant bereikbaar maakt.

Route 1: de ingebouwde MCP Server-integratie

Home Assistant heeft sinds versie 2025.2 een eigen MCP-server. In de documentatie heet de integratie "Model Context Protocol Server". De hoofd-URL is /api/mcp. Oudere handleidingen uit 2025 noemen een ander pad, want de core-changelog van 2025.11 vermeldt "Update the MCP Server API endpoint to mcp".

De belangrijkste zin uit de documentatie (gelezen op 13 november 2026, docs-versie 2026.11.1) staat bij de voorwaarden. Over de hoofd-URL staat daar: "By default, it exposes all tools". Daaronder valt de toolset Home Assistant. Volgens dezelfde pagina kan die set alle entiteiten, logs en geschiedenis lezen en elke actie uitvoeren. Zet je de integratie aan en verander je niets? Dan mag Claude dus ook je alarm uitschakelen of je slot openen.

De andere toolset heet Device control. Die geeft Claude dezelfde tools als je spraakassistent. De documentatie zegt het zo: "With Device control, it can only control or see the entities that you have exposed on the exposed entities page." Claude ziet dan alleen wat jij zelf hebt vrijgegeven voor spraakassistenten.

Welke opties staan standaard aan?

De integratie heeft vier opties. Ze gelden alleen voor de hoofd-URL /api/mcp.

  • Expose all AI tools: staat standaard aan. Dan geeft de hoofd-URL elke toolset vrij, ook sets die integraties later toevoegen.
  • AI tools: de sets die de hoofd-URL vrijgeeft als je Expose all AI tools uitzet.
  • Require an administrator account: staat standaard aan. Alleen beheerdersaccounts mogen de hoofd-URL gebruiken.
  • Read-only: staat standaard uit. Zet je het aan, dan geeft de hoofd-URL alleen tools vrij die gemarkeerd zijn als tools die niets veranderen.

Heb je de integratie ingesteld voordat de optie Expose all AI tools bestond? Dan staat die optie volgens de documentatie uit. Controleer het toch, want je wilt zeker weten welke sets aan staan.

De integratie beperken tot Device control

Werk in deze volgorde. Zo heeft Claude nooit meer toegang dan je bedoelt.

  1. Ga naar de pagina met vrijgegeven entiteiten voor spraakassistenten. Geef alleen vrij wat Claude mag zien, bijvoorbeeld lampen en de thermostaat.
  2. Open de opties van de MCP Server-integratie en zet Expose all AI tools uit.
  3. Kies onder AI tools alleen Device control.
  4. Mag Claude alleen de status lezen en niets schakelen? Zet dan ook Read-only aan.

Er is ook een kortere weg. Elke toolset heeft een eigen URL. Je vindt die onder "Individual URLs" in Settings > System > AI. De documentatie geeft één voorbeeld: /api/mcp/assist geeft alleen Device control vrij. Let op hoe die losse URL's zich gedragen. Ze negeren de vier opties hierboven en zijn nooit read-only. Alle losse URL's behalve die van Device control vereisen een beheerdersaccount. Met /api/mcp/assist kun je dus een gewoon account zonder beheerdersrechten gebruiken. Lekt er iets, dan is dat een veel kleinere sleutel.

Hoe Claude inlogt bij de ingebouwde server

De huidige documentatie beschrijft OAuth 2.0 met PKCE (Proof Key for Code Exchange). Home Assistant ondersteunt ook OAuth Client ID Metadata Documents. Daardoor stelt een AI-client de client-ID en de callback-URL zelf in. Home Assistant gebruikt geen client secret. Volgens de troubleshooting-sectie volgt Home Assistant de conceptstandaard draft-ietf-oauth-client-id-metadata-document en niet RFC 7591 Dynamic Client Registration. Voor Claude kies je daarom "Use Claude's published identity" als OAuth-client. Je hoeft geen token te kopiëren.

Route 2: het communityproject ha-mcp

ha-mcp is een losse MCP-server onder de GitHub-organisatie homeassistant-ai. Dat is niet de organisatie home-assistant waar de core in staat. De README zegt nergens dat het project bij Home Assistant of Nabu Casa hoort. Het project heeft een MIT-licentie. De huidige README telt op 15 november 2026 86 tools. Dat is een veel bredere set dan Device control, dus beperk ha-mcp minstens zo streng als de ingebouwde server.

Welke versie installeer je?

De laatste stabiele release is v9.2.0, uitgebracht op 11 november 2026. Daarnaast verschijnen er v9.3.0.devN-builds, gemarkeerd als pre-release. De README zegt: "Dev releases (.devN) are published on every push to master." Dat gebeurt soms meerdere keren per dag. Ons advies: gebruik de stabiele versie en update bewust. Het project zelf waarschuwt dat dev-builds bugs kunnen bevatten en raadt voor productie stabiele releases aan. Maar een server die je hele huis kan aansturen, wil je niet elke paar uur zien veranderen.

Op Home Assistant OS installeer je ha-mcp als app. Voeg de repository https://github.com/homeassistant-ai/ha-mcp toe via Settings > Apps > Install app > het menu met drie puntjes > Repositories. Installeer daarna "Home Assistant MCP Server" en klik op Start. Je unieke MCP-URL staat in het tabblad Logs. Controleer na de installatie welk versienummer de app toont. Update daarna alleen als je de release notes hebt gelezen.

Draai je ha-mcp als Python-pakket met uvx? De README gebruikt dan ha-mcp@latest. Zet daar een vaste versie neer:

uvx --python 3.14 ha-mcp@9.2.0

Een eigen account, geen token op je eigen login

De README geeft twee manieren om te kiezen als welk beheerdersaccount ha-mcp werkt. De eerste is een long-lived access token op je eigen account. Lekt dat token, dan werkt het overal. Bovendien staat elke wijziging van ha-mcp dan op jouw naam. De tweede, veiligere manier is een apart account onder Settings > People > Add person. Zet daar inloggen aan, beperk het account tot lokale toegang en geef het beheerdersrechten. De README waarschuwt: "Never use your own login for the second option."

Gebruik verder de knoppen die het project zelf noemt. Er is een Read Only Mode-schakelaar. Je kunt losse tools aan- en uitzetten. En er zijn beveiligingsregels waarbij jij een tool-aanroep eerst goedkeurt. Read-only verbindingen verbergen schrijftools en blokkeren schrijfaanroepen. Hoe je goedkeuring voor acties in het algemeen regelt, lees je in acties van een AI-agent laten goedkeuren voordat ze worden uitgevoerd.

Het geheime pad is het wachtwoord

Een client op een ander apparaat kan op twee manieren met ha-mcp verbinden: op afstand via Home Assistant, of via het lokale netwerk. Bij de HA-MCP-integratie staan beide standaard uit. Lokaal ziet de URL er bij de app uit als http://<ha-ip>:9583/private_<random>; de HA-MCP-integratie gebruikt poort 9584. Op afstand via Home Assistant gebruik je een webhook-URL zoals https://example.com/api/webhook/<webhook-id>. Bij de app installeer je daarvoor ook de Webhook Proxy-app; de HA-MCP-integratie heeft die proxy al ingebouwd.

Zonder extra instelling is de geheime URL de enige sleutel. Wie de URL kent, praat met je huis. Plak hem dus niet in een chat, een issue of een screenshot. Wil je er een echte login voor? Zet dan de authenticatiemodus op ha_auth. Dan vraagt ha-mcp om een Home Assistant-login en geldt de geheime URL niet meer als bewijs. Meer hierover lees je in geheimen buiten een AI-agent houden.

Waarom bereikbaarheid de echte keuze is

Het Help Center van Claude is hier duidelijk. Claude verbindt met je remote MCP-server vanuit de cloud-infrastructuur van Anthropic, niet vanaf je eigen apparaat. Dat geldt voor elke Claude-client: claude.ai, Claude Desktop, Cowork en de mobiele apps. Een server in een privénetwerk of achter een VPN (virtueel privénetwerk) krijgt geen verbinding. De Home Assistant-documentatie zegt hetzelfde: "Claude connects to your MCP server from the cloud, also when you use Claude Desktop." Remote connectors vereisen bovendien HTTPS op poort 443; een URL met bijvoorbeeld poort 8443 werkt niet. Lokaal geconfigureerde MCP-servers via claude_desktop_config.json gebruiken wel je eigen netwerk.

Dat heeft een direct gevolg. Staat Home Assistant alleen in je tailnet, dan werkt de connector in Claude Desktop niet. Dat geldt ook als je laptop Home Assistant gewoon kan bereiken, want de verbinding komt niet van je laptop.

Claude Code is een ander geval. De Home Assistant-documentatie geeft daarvoor een eigen setup en schrijft voor de ingebouwde server HTTPS voor. De ha-mcp-documentatie toont voor lokale verbindingen met Claude Code ook HTTP. Test het daarom zelf met een HTTPS-adres dat alleen in je tailnet bestaat. Werkt dat, dan hoeft Home Assistant voor Claude Code niet publiek te zijn.

Volgens het Help Center zijn custom connectors beschikbaar op Free (één connector), Pro, Max, Ultra, Team en Enterprise. Op Team kunnen alleen Owners en Primary Owners ze toevoegen. Twijfel je welk abonnement past, lees dan welk Claude-abonnement je nodig hebt.

Drie manieren om Home Assistant bereikbaar te maken

Zet nooit poort 8123 direct open in je router. Dan staat de inlogpagina van je hele huis rechtstreeks op internet. Heb je zelf geen certificaat ingesteld, dan gaat dat verkeer bovendien zonder HTTPS. De remote connector van Claude vereist HTTPS op poort 443. Kies een van de drie routes hieronder.

Home Assistant Cloud van Nabu Casa

Home Assistant Cloud is het abonnement van Nabu Casa dat veilige toegang op afstand toevoegt. Volgens de Home Assistant-site gaat het vanaf 2 december 2026 Home Assistant Link heten. De prijzenpagina van Nabu Casa gebruikt die naam al. Op 15 november 2026 toonde die pagina €7,50 per maand of €75,00 per jaar, exclusief belasting, met een gratis proefperiode van 31 dagen. De pagina heeft een valutakiezer. Kies daar EUR voor het bedrag in euro.

Volgens de MCP-documentatie van Home Assistant vermijd je met Home Assistant Cloud (https://<your-id>.ui.nabu.casa) de valkuilen van reverse proxy's en tunnels. Je MCP-URL wordt dan https://<your-id>.ui.nabu.casa/api/mcp, of met /api/mcp/assist aan het eind als je alleen Device control wilt. Voor de meeste huishoudens is dit de route met de minste onderdelen.

Tailscale Funnel

Tailscale Funnel zet een lokale dienst open voor iedereen op internet, ook voor mensen zonder Tailscale. Volgens de documentatie is Funnel in bèta en beschikbaar op alle abonnementen. Je hebt vier dingen nodig: Tailscale v1.38.3 of nieuwer, MagicDNS, HTTPS-certificaten voor je tailnet, en het node-attribuut funnel in je policy-bestand. Funnel luistert alleen op poort 443, 8443 en 10000. Het verkeer valt onder bandbreedtelimieten die je niet kunt aanpassen.

Draait Tailscale met de CLI op dezelfde machine als Home Assistant, bijvoorbeeld bij Home Assistant Container op Debian? Start Funnel dan op de achtergrond:

sudo tailscale funnel --bg 8123
tailscale funnel status

Met --bg blijft Funnel draaien, ook na een herstart. tailscale funnel status laat zien wat Funnel publiceert. De publieke naam valt altijd onder het ts.net-domein van je tailnet. Uitzetten doe je door off achter het commando te zetten dat je gebruikte, of met tailscale funnel reset. Gebruik je Home Assistant OS met de Tailscale-app? Kijk dan in de documentatie van die app of en hoe hij Funnel aanzet.

Volgens Tailscale kan iedereen een Funnel-URL bereiken, ook zonder Tailscale-account. De OAuth-login van de ingebouwde server, of ha_auth bij ha-mcp, is dan wat onbekenden tegenhoudt. Wat Tailscale zelf wel en niet ziet van je verkeer, staat in hoe veilig Tailscale is.

Een VPS als reverse proxy, voor CGNAT-lijnen

Sommige aansluitingen, vaak mobiel internet, zitten achter CGNAT (carrier-grade NAT, network address translation bij de provider). Je hebt dan geen eigen publiek IPv4-adres. Inkomende verbindingen komen dus nooit bij je router aan. Een kleine VPS lost dat op. Je thuisserver bouwt een uitgaande tunnel naar de VPS. De VPS regelt TLS (transport layer security) en stuurt het verkeer door. Hoe je die tunnel opzet, lees je in een reverse tunnel via een VPS achter CGNAT.

Deze route kost het meeste werk, maar je houdt alles in eigen hand. Draai je meer MCP-servers, dan kan dezelfde VPS die ook hosten. Zie MCP-servers op een VPS draaien.

Verzoeken via een proxy worden geweigerd

Bij Funnel en bij de VPS-route komt het verkeer via een proxy binnen. De HTTP-documentatie van Home Assistant zegt: "Requests from reverse proxies are blocked if these options are not set." Het gaat om Trust X-Forwarded-For en Trusted proxies. Zet de eerste aan. Vul bij de tweede het adres of netwerk van je proxy in. Zet daar geen heel breed bereik neer. Elk adres in die lijst mag namelijk zeggen van welk IP-adres een verzoek komt.

Claude Desktop en Claude Code koppelen

De Home Assistant-documentatie geeft voor Claude Desktop deze stappen:

  1. Ga naar Settings > Connectors en kies Add > Add custom connector.
  2. Vul als naam Home Assistant in en plak je MCP-URL, bijvoorbeeld https://<your-id>.ui.nabu.casa/api/mcp/assist.
  3. Kies Add. Claude controleert de server en toont een dialoog.
  4. Kies bij Authentication "Sign in now" en bij OAuth client "Use Claude's published identity".
  5. Kies Add, open de pagina van de nieuwe connector en kies Connect.
  6. Log in bij je Home Assistant.

Gebruik bij stap 6 het account dat je voor Claude hebt bedoeld. Dat is niet automatisch je eigen beheerdersaccount. Voor Claude Code zijn het twee commando's:

claude mcp add --transport http home-assistant https://ha.example.com/api/mcp/assist
claude mcp login home-assistant

Na het tweede commando log je in je browser in bij Home Assistant. Binnen een sessie kun je ook via /mcp inloggen. Staat dezelfde URL ook als connector in claude.ai? Dan wint volgens de Claude Code-documentatie de server die je in Claude Code hebt toegevoegd.

Wanneer is de authenticatie veranderd?

Dit is een open vraag, en we laten hem open. Oudere artikelen over de ingebouwde server beschrijven long-lived tokens en alleen vrijgegeven entiteiten. De huidige documentatie beschrijft OAuth 2.0 met PKCE en Client ID Metadata Documents. In welke release dat precies veranderde, konden wij in de release notes niet vaststellen.

Wat wel vaststaat: de core-changelog van 2025.11 noemt het nieuwe endpoint mcp en "Update MCP server to support the newer HTTP protocol". De core-changelog van 2026.5 noemt "Add client_id_metadata_document_supported to the OAuth Authorization Server Metadata". Volgens die pull request accepteerde Home Assistant URL's als client-ID al via IndieAuth. Die wijziging maakte dus vooral zichtbaar wat al kon. Een issue over mislukte OAuth met de MCP-connector van ChatGPT en Claude is geopend op 6 oktober 2025. Op 13 november 2026 stond het nog open. Draai je een oudere versie? Lees dan de changelogs op home-assistant.io voor jouw release en volg de documentatie van die versie.

Aanwezigheid, alarm en sloten naar Anthropic: telt de AVG mee?

Ook dit is een vraag die je zelf moet beantwoorden. Volgens artikel 2, lid 2, onder c, van de AVG geldt de verordening niet voor verwerking door een natuurlijk persoon bij een zuiver persoonlijke of huishoudelijke activiteit. Overweging 18 voegt toe: "with no connection to a professional or commercial activity". Voor een gezin dat de eigen lampen schakelt, ligt dat anders dan voor een kleine zaak of een vakantiewoning met gasten. Of aanwezigheid, alarmstatus en slotstatus in jouw geval persoonsgegevens van anderen zijn, is een juridische vraag. Die beslissen wij niet voor je.

Twee dingen kun je nu wel doen. Geef sloten, alarm en aanwezigheidssensoren niet vrij aan Device control als Claude ze niet nodig heeft. En lees de privacypagina van Anthropic over training. Bij consumentenabonnementen hangt het af van de instelling Model Improvement. Commerciële producten zoals Team, Enterprise en de API gebruiken invoer en uitvoer standaard niet voor training. Volgens die pagina vallen ruwe gegevens uit connectors, ook uit remote en lokale MCP-servers, buiten de gegevens voor modelverbetering en buiten feedbackgegevens. Kopieer je zulke gegevens rechtstreeks in je gesprek met Claude, dan kunnen ze er wel in terechtkomen.

FAQ

Kan Claude Desktop mijn Home Assistant via Tailscale bereiken zonder Funnel?

Niet via een remote connector. Claude Desktop verbindt met een remote MCP-server vanuit de cloud van Anthropic, niet vanaf je eigen computer. Een Home Assistant die alleen in je tailnet bestaat, is daar onbereikbaar. Gebruik Home Assistant Cloud, Tailscale Funnel of een VPS als reverse proxy. Met een lokaal geconfigureerde MCP-server in claude_desktop_config.json, bijvoorbeeld ha-mcp via mcp-remote, gebruikt Claude Desktop wel je eigen netwerk en kan een verbinding via je tailnet zonder Funnel werken. Claude Code is een apart geval: test daar of een HTTPS-adres in je tailnet volstaat.

Waarom ziet Claude mijn slot of thermostaat niet?

Met alleen de toolset Device control ziet Claude alleen entiteiten die je hebt vrijgegeven voor spraakassistenten. Een entiteit die daar niet staat, bestaat voor Claude niet. Geef de thermostaat vrij als Claude hem mag bedienen. Laat het slot weg als je dat niet wilt.

Is de ingebouwde MCP Server veiliger dan ha-mcp?

De ingebouwde server gebruikt OAuth. Met /api/mcp/assist beperk je hem tot Device control, met een gewoon account zonder beheerdersrechten. De huidige README van ha-mcp vermeldt 86 tools; de README van v9.2.0 vermeldde er 87. ha-mcp gebruikt standaard een geheime URL als sleutel, tenzij je ha_auth aanzet. Wil je alleen apparaten schakelen, kies dan de ingebouwde server met Device control. Kies ha-mcp alleen als je de extra tools echt nodig hebt, met een eigen account en waar het kan Read Only Mode.

Welke Home Assistant-versie heb ik nodig voor de MCP-server?

De integratie bestaat sinds Home Assistant 2025.2. Het pad /api/mcp hoort bij latere versies: de core-changelog van 2025.11 vermeldt de wijziging van het endpoint naar mcp. Volg je een handleiding uit begin 2025, dan klopt het pad daarin waarschijnlijk niet meer. Controleer de documentatie die bij jouw versie hoort.

Was dit artikel nuttig?