Home Assistant MCP Server

Überblick

Zusammenfassung der Dokumentation und Konfiguration von homeassistant-ai/ha-mcp, automatisch erstellt und übersetzt. Stimmt etwas nicht, oder betreust du das Projekt und möchtest hier deinen eigenen Text? Melde dich

Unterstützt

• Öffnet sich in der Seitenleiste Eine eigene Seite öffnet sich in Home Assistant.

• Aktiv gepflegt Das Projekt hat in den letzten sechs Monaten eine neue Version oder Änderung veröffentlicht.

Einrichtung

Füge ihr App-Repository unter Einstellungen > Apps hinzu, installiere sie dann und starte sie.

Aus der Dokumentation

Berechtigungen

• Host-NetzwerkNutzt direkt das Netzwerk des Hosts statt eines eigenen.
• Home Assistant-APIKann Home Assistant auslesen und steuern.
• Supervisor-APIKann mit dem Supervisor sprechen, der Apps und das System verwaltet.

Netzwerk

• 9583/tcp

Konfiguration

• TLS-Zertifikate überprüfenÜberprüfe das TLS-Zertifikat des Home Assistant-Servers. Deaktiviere dies nur in einem vertrauenswürdigen Netzwerk, für ein selbstsigniertes Zertifikat oder bei einer Hostnamen-Abweichung: Dies schwächt die Transportsicherheit.
• Home-Assistant-Tool-GleichzeitigkeitOptionale Begrenzung für äußere Home Assistant-Tool-Aufrufe über alle Sitzungen hinweg. Interne REST-, WebSocket- und tool-spezifische Fan-Out-Gleichzeitigkeit bleibt unverändert. 0 belässt das Verhalten unbegrenzt. Ein Aufruf, der auf Kapazität wartet, schlägt nach 60 Sekunden fehl. Bereich 0–32.
• Backup-HinweisstufeWie nachdrücklich KI-Assistenten angewiesen werden, vor riskanten Änderungen ein vollständiges Home Assistant-Backup vorzuschlagen. Ändert nur diesen Hinweis; automatische Bearbeitungs-Backups haben ihre eigene Einstellung.
• Eigene Server-AnweisungenText, den jeder verbundene KI-Assistent als Teil der MCP-Server-Anweisungen erhält – zum Beispiel, wo Notizen zum Haushalt liegen und wann sie gelesen oder aktualisiert werden sollen. Auch Teil des Prompts von Home-Assistant-Sprachassistenten (Assist), die dieses Toolset nutzen. Gedacht für Hinweise, die alle deine Clients auf einmal erreichen sollen; halte ihn kurz und ohne Geheimnisse. Leer lassen, um nichts hinzuzufügen. Erfordert einen Neustart; Clients sehen die Änderung nach dem erneuten Verbinden.
• Tool-Suche aktivierenErsetze den vollständigen Tool-Katalog durch eine suchend basierte Erkennung. Reduziert den Leerlaufkontext um etwa 90 % auf ca. 5K Token. ⚠️ Aktiviere dies NICHT in Clients mit eigener integrierter Tool-Suche / verzögerten Tools (claude.ai, Claude Desktop, Claude Code) — die beiden Suchschichten kollidieren, und die integrierte Tool-Suche des Clients ist dort die bessere Wahl; lasse dies ausgeschaltet. Ob Tools verzögert werden, hängt von deiner Client- und Modellkombination ab: Verwende dies, wenn dein Setup den vollständigen Katalog im Voraus lädt — Modelle ohne native verzögerte Tools (z. B. Gemini, OpenAI-kompatible lokale Modelle, Claude Haiku), Clients, die alle Tool-Schemas unabhängig vom Modell einbetten (z. B. GitHub Copilot CLI), oder kleinere Kontextfenster. Einige Codex-Modelle und ChatGPT beinhalten ebenfalls verzögerte Tools — überprüfe deinen Client bzw. dein Modell direkt, um dessen Funktionen zu bestätigen, damit du dies nicht unnötig aktiviert lässt. Tools werden über ha_search_tools gefunden und über kategorisierte Proxys (lesen/schreiben/löschen) ausgeführt. Erfordert einen App-(Add-on-)Neustart, um wirksam zu werden — verbinde dich danach neu oder aktualisiere den MCP-Server in deinem KI-Client, damit dieser die Tool-Liste neu lädt. Das alleinige Neustarten der App (des Add-ons) aktualisiert die zwischengespeicherte Tool-Liste eines Clients NICHT; dies gilt nach jeder Änderung einer Einstellung hier.
• Max. Tool-SuchergebnisseMaximale Anzahl versteckter Tools, die pro ha_search_tools-Aufruf zurückgegeben werden, wenn die Tool-Suche aktiviert ist; ein angepinntes Tool, das in diesen obersten Ergebnissen landet, wird als kurzer Name-only-Eintrag zusätzlich oben hinzugefügt. Niedrigere Werte (2-3) sparen Kontex-Token, können aber relevante Tools verfehlen. Erfordert Neustart. Bereich 2–10.
• Tool-Sicherheitsrichtlinien aktivieren (erweitert)Gating kritischer Tool-Aufrufe (Schloss-/Alarmsteuerung, Automatisierungsschreibvorgänge usw.) hinter Benutzergenehmigung. Wenn ein geschütztes Tool aufgerufen wird, weist der Agent den Benutzer an, den Tab Tool-Sicherheitsrichtlinien in der Web-UI zu öffnen und auf Genehmigen zu klicken, bevor der Aufruf fortgesetzt wird. Tool-bezogene Regeln mit optionalen Argumentbedingungen werden im Tab Tool-Sicherheitsrichtlinien konfiguriert. Standardmäßig ausgeschaltet. Erfordert Neustart, um wirksam zu werden.
• KI-Agenten erlauben, Tool-Sicherheitsrichtlinien zu bearbeitenRegistriert das Tool ha_manage_security_policy, das verbundenen KI-Agenten erlaubt, die Tool-Sicherheitsrichtlinien zu lesen und neu zu schreiben — einschließlich des Entfernens von Genehmigungsschranken. Standardmäßig deaktiviert. Unabhängig von der Option „Tool-Sicherheitsrichtlinien“ oben: Dies steuert, wer die Regeln bearbeiten kann, nicht ob sie erzwungen werden. Das Tool kann ausstehende Genehmigungen nicht sehen oder entscheiden. Um einen Menschen in der Schleife zu halten, schütze das Tool, bevor du es aktivierst: Aktiviere „security gated“ für „Manage Security Policy“ auf dem Tab „Tools“ der Web-UI. Erfordert einen Neustart, um wirksam zu werden.
• Nur-Lese-ModusSchaltet alle Schreib-Tools aus und entzieht Tools die Fähigkeit, Schreib- oder destruktive Aufrufe auszuführen. Gemischte Lese-/Schreib-Tools — Backups, Apps (Add-ons), Energieeinstellungen, Sprach-Pipelines und der Code-Modus, wenn aktiviert — bleiben verfügbar, wobei ihre Schreiboperationen blockiert sind. Gleicher Umschalter wie auf dem Web-UI-Tab Tools. Standardmäßig aus. Erfordert einen Neustart, um wirksam zu werden.
• Geheimnisse schwärzenEntfernt Geheimnisse aus Werkzeugantworten, bevor sie den KI-Assistenten erreichen. App- (Add-on-)Optionen und Integrationsfelder, die als Passwörter markiert sind, werden durch eine Markierung für gesetzt/leer ersetzt (damit „ist diese Zugangsmarke konfiguriert?“ beantwortet werden kann), und andere Werkzeugantworten werden von Geheimnissen bereinigt, die der Server bereits gesehen hat (Werte, die kürzer als 6 Zeichen sind, werden übersprungen, da das Ersetzen kleiner Fragmente unrelated Ausgaben beschädigen würde). Andere Felder werden nicht erkannt, außer privaten Schlüsseln in App-Optionen und den unten aufgeführten App-Optionennamen. Standardmäßig aus.
• Zusätzliche App-Optionsschlüssel zum SchwärzenApp- (Add-on-)Optionsnamen zum Schwärzen wie Passwortfelder für Apps, deren Schema ein Geheimnis im Klartext speichert (zum Beispiel backup_password). Trenne Namen mit Kommas oder Zeilenumbrüchen. Ein Name gilt für jede App; schreibe app_slug:name, um ihn auf eine App zu beschränken. Das Benennen einer Optionsgruppe deckt jede Option darin ab. Wird nur verwendet, wenn Geheimnisse schwärzen aktiv ist. Standardmäßig leer.
• Best-Practice-Skills bei Schreibvorgängen anhängenHauptschalter für die Funktion zur Bereitstellung von Schreib-Tool-Skill-Inhalten (Issue #1182). Wenn aktiviert (Standard), fügen die sechs Konfigurations-Schreibtools (Automatisierungen, Skripte, Szenen, Helfer, Dashboards, rohes YAML) die kanonischen Home-Assistant-Best-Practice-Referenzdateien unter skill_content bei jedem erfolgreichen Schreibvorgang an, plus automatisches Einbetten aller Referenzabschnitte, die von Best-Practice-Warnungen zitiert werden. Jedes Tool stellt auch einen per-Aufruf-Parameter MandatoryBPS zur Verfügung, den der Agent bei nachfolgenden Aufrufen auf false setzen kann, sobald er den Inhalt hat. Wenn dieser Hauptschalter ausgeschaltet ist, wird KEIN skill_content ausgegeben, unabhängig vom per-Aufruf-Parameter oder BP-Warnungen. Empfohlen EIN als erste Wahl; deaktiviere nur für Modelle mit sehr kleinen Kontextfenstern. Das Ausschalten davon kann die Schreibgenauigkeit beeinträchtigen. Erfordert Neustart, um wirksam zu werden.
• Strikter Best-Practices-ModusStrikter Modus: verhindert, dass der Client das Tool verwendet, bis er nachweisen kann, dass er die Best Practices gelesen hat. Während er eingeschaltet ist, werden die sechs Best-Practice-Schreibtools (Automatisierungen, Skripte, Szenen, Helfer, Dashboards, rohes YAML) blockiert und geben einen Fehler zurück, der den Client anweist, das Best-Practices-Skill über ha_get_skill_guide zu lesen und den dort erhaltenen Bestätigungsschlüssel zurückzugeben. Während er eingeschaltet ist, ist das ha_get_skill_guide-Tool gesperrt aktiviert – es ist der einzige Herausgeber des Bestätigungsschlüssels. Kind der Option Best-Practice-Skills bei Schreibvorgängen anhängen oben und inert, während dieser Elternteil ausgeschaltet ist. Erfordert Neustart, um wirksam zu werden.
• Automatische Backup-BearbeitungenSpeichere einen Schnappschuss einer Entität, bevor ein Schreib- oder Lösch-Tool-Aufruf sie ändert. Solange dies deaktiviert ist, verweigern die Datei- und Raw-YAML-Tools (ha_write_file, ha_delete_file, ha_config_set_yaml) das Schreiben.
• Auto-Backup-Drosselung (Minuten)Wie oft das Auto-Backup dieselbe Entität erfassen darf. 0 erfasst bei jedem Schreiben; N größer als 0 erfasst höchstens einen Schnappschuss pro N Minuten und Entität. Bereich 0–1440.