Zum Inhalt springen
SONOYA.com
KI

MCP-Server in Python bauen: Claude liest Home Assistant

Eigenen MCP-Server in Python bauen: mit SDK 2, uv und Inspector Tools und eine Ressource schreiben und in Claude Code und Claude Desktop nutzen.

Von

Python-Logo als helle Linienzeichnung auf dunkelrotem Verlauf, Sinnbild für einen selbst geschriebenen MCP-Server in Python

Fertige MCP-Server gibt es für GitHub, Notion oder den Browser. Für Deine eigenen Daten gibt es keinen: die interne API im Büro, die SQLite-Datenbank mit Deinen Messwerten oder das Home-Assistant-Haus. Ein eigener MCP-Server in Python ist dafür die Lösung, und mit dem offiziellen SDK besteht er aus erstaunlich wenig Code. In dieser Anleitung bauen wir einen Server, über den Claude die Sensorwerte aus Home Assistant liest, testen ihn mit dem MCP Inspector und binden ihn in Claude Code und Claude Desktop ein.

Der Code ist mit dem Python-SDK mcp 2.3.0, Python 3.13 und uv 0.11 auf macOS getestet. Statt einer echten Home-Assistant-Instanz lief dabei ein kleiner Nachbau der REST-API, der Antworten im Format von Home Assistant liefert. Für Dein echtes Haus ändern sich nur Adresse und Token.

MCP in drei Sätzen

Das Model Context Protocol ist ein offener Standard, über den eine KI-Anwendung wie Claude Code mit externen Programmen spricht. Ein MCP-Server bietet dabei vor allem zwei Dinge an: Tools, also Funktionen, die das Modell selbstständig aufrufen darf, und Ressourcen, also Daten, die Du oder die Anwendung gezielt in den Kontext holt. Lokale Server laufen als normales Programm auf Deinem Rechner, und die Anwendung spricht über die Standardein- und -ausgabe (stdio) mit ihnen.

Wenn Du nur fertige Server einbinden willst, ist MCP-Server in Claude Code und Codex einrichten der richtige Artikel. Hier geht es darum, selbst einen zu schreiben.

Wichtig: Aus FastMCP wurde MCPServer

Viele Tutorials im Netz beginnen mit from mcp.server.fastmcp import FastMCP. Das funktioniert mit dem aktuellen SDK nicht mehr. Seit Version 2 heißt die Klasse MCPServer, und der alte Import bricht mit ModuleNotFoundError ab. Das Prinzip ist gleich geblieben: Du schreibst normale Python-Funktionen mit Typangaben und Docstring, und das SDK macht daraus die Beschreibung, die Claude sieht. Alles Weitere zum Umstieg steht im offiziellen Migrationsleitfaden zum Python-SDK.

Was Du brauchst

  • uv, den Paketmanager für Python. Er installiert bei Bedarf auch gleich eine passende Python-Version.
  • Home Assistant im Netzwerk, erreichbar zum Beispiel unter http://homeassistant.local:8123. Falls Du es erst einrichten musst, hilft Home Assistant auf dem Raspberry Pi installieren.
  • Claude Code oder Claude Desktop als Anwendung, die den Server nutzt, und Node.js für den MCP Inspector.

Den Token für Home Assistant erstellst Du in der Weboberfläche: Klick unten links auf Deinen Benutzernamen, wechsle in den Reiter Sicherheit (englisch Security) und wähle ganz unten im Abschnitt für langlebige Zugangstoken (Long-lived access tokens) die Schaltfläche zum Erstellen eines Tokens. Gib ihm einen Namen wie „Claude MCP” und kopiere ihn sofort, denn Home Assistant zeigt ihn nur einmal an.

Schritt 1: Projekt mit uv anlegen

Lege einen Ordner für das Projekt an und füge das offizielle SDK hinzu:

Code
uv init ha-sensoren
cd ha-sensoren
uv add "mcp[cli]"

uv init erzeugt ein kleines Python-Projekt mit pyproject.toml, uv add installiert das SDK in eine eigene virtuelle Umgebung im Ordner .venv. Der Zusatz [cli] bringt den Befehl mcp mit. Das HTTP-Paket httpx2, mit dem wir gleich Home Assistant abfragen, installiert das SDK selbst mit, Du musst es nicht extra hinzufügen. Mit uv run mcp version prüfst Du, welche Version installiert ist; die Anleitung setzt mindestens 2.0.0 voraus.

Schritt 2: Tools und Ressource schreiben

uv init hat eine Beispieldatei main.py angelegt, die wir nicht brauchen. Lösche sie und lege im selben Ordner eine neue Datei server.py mit diesem Inhalt an:

Code
import logging
import os
import re

import httpx2
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp.types import ToolAnnotations

logging.basicConfig(level=logging.INFO)
log = logging.getLogger("ha-sensoren")

HA_URL = os.environ["HA_URL"].rstrip("/")
HA_TOKEN = os.environ["HA_TOKEN"]
ENTITY_ID = re.compile(r"^sensor\.[a-z0-9_]{1,100}$")
NUR_LESEN = ToolAnnotations(read_only_hint=True)

mcp = MCPServer(
    "ha-sensoren",
    instructions="Liest Sensorwerte aus Home Assistant. Kann nichts schalten.",
)


async def ha_get(pfad: str):
    """Fragt die REST-API von Home Assistant ab und gibt das JSON zurück."""
    headers = {"Authorization": f"Bearer {HA_TOKEN}"}
    try:
        async with httpx2.AsyncClient(base_url=HA_URL, headers=headers, timeout=10) as client:
            antwort = await client.get(pfad)
    except httpx2.HTTPError as fehler:
        log.warning("Home Assistant nicht erreichbar: %s", fehler)
        raise ToolError(f"Home Assistant unter {HA_URL} ist nicht erreichbar.")
    if antwort.status_code == 401:
        raise ToolError("Home Assistant lehnt den Token ab (401). HA_TOKEN prüfen.")
    if antwort.status_code == 404:
        raise ToolError("Diese Entität gibt es in Home Assistant nicht.")
    antwort.raise_for_status()
    return antwort.json()


def als_zeile(zustand: dict) -> str:
    """Macht aus einem Zustandsobjekt eine kurze, lesbare Zeile."""
    attribute = zustand.get("attributes", {})
    name = attribute.get("friendly_name", "")
    einheit = attribute.get("unit_of_measurement", "")
    return f"{zustand['entity_id']} ({name}): {zustand['state']} {einheit}".strip()


async def alle_sensoren() -> list[dict]:
    zustaende = await ha_get("/api/states")
    return [z for z in zustaende if z["entity_id"].startswith("sensor.")]


@mcp.tool(annotations=NUR_LESEN)
async def sensoren_suchen(suchbegriff: str = "") -> str:
    """Sucht Sensoren in Home Assistant und zeigt ihren aktuellen Wert.

    Args:
        suchbegriff: Teil des Namens oder der Entity-ID, etwa "wohnzimmer"
            oder "temperatur". Leer lassen, um alle Sensoren zu sehen.
    """
    begriff = suchbegriff.strip().lower()
    if len(begriff) > 50:
        raise ToolError("Der Suchbegriff darf höchstens 50 Zeichen lang sein.")
    treffer = [
        z for z in await alle_sensoren()
        if begriff in z["entity_id"].lower()
        or begriff in z.get("attributes", {}).get("friendly_name", "").lower()
    ]
    if not treffer:
        return "Keine passenden Sensoren gefunden."
    zeilen = [als_zeile(z) for z in treffer[:50]]
    if len(treffer) > 50:
        zeilen.append(f"... und {len(treffer) - 50} weitere. Suche genauer.")
    return "\n".join(zeilen)


@mcp.tool(annotations=NUR_LESEN)
async def sensor_lesen(entity_id: str) -> dict:
    """Liest einen einzelnen Sensor mit Wert, Einheit und letzter Änderung.

    Args:
        entity_id: Die Entity-ID des Sensors, zum Beispiel
            "sensor.wohnzimmer_temperatur".
    """
    if not ENTITY_ID.fullmatch(entity_id):
        raise ToolError("Erlaubt sind nur Entity-IDs der Form sensor.name_mit_unterstrichen.")
    zustand = await ha_get(f"/api/states/{entity_id}")
    attribute = zustand.get("attributes", {})
    return {
        "entity_id": zustand["entity_id"],
        "name": attribute.get("friendly_name"),
        "wert": zustand["state"],
        "einheit": attribute.get("unit_of_measurement"),
        "zuletzt_geaendert": zustand.get("last_changed"),
    }


@mcp.resource("homeassistant://sensoren", mime_type="text/plain")
async def sensorliste() -> str:
    """Alle Sensoren mit aktuellem Wert, eine Zeile pro Sensor."""
    return "\n".join(als_zeile(z) for z in await alle_sensoren())


if __name__ == "__main__":
    mcp.run(transport="stdio")

Speichere die Datei. Die wichtigsten Stellen kurz erklärt:

  • @mcp.tool() macht aus einer Funktion ein Tool. Funktionsname, Parameter mit Typ und der Docstring landen als Beschreibung bei Claude. Je klarer der Docstring sagt, wofür das Tool da ist und wie ein Parameter aussieht, desto zuverlässiger ruft Claude es richtig auf.
  • sensoren_suchen und sensor_lesen arbeiten zusammen: Claude kennt Deine Entity-IDs nicht, sucht also erst nach „wohnzimmer” und liest dann gezielt einen Sensor. Weil sensor_lesen ein Dictionary zurückgibt, liefert das SDK die Werte zusätzlich als strukturierte Daten aus.
  • @mcp.resource() stellt die komplette Sensorliste unter der Adresse homeassistant://sensoren bereit. Anders als ein Tool ruft Claude eine Ressource nicht von sich aus auf, sondern Du holst sie bei Bedarf in den Kontext.
  • ToolError sorgt dafür, dass Claude eine verständliche Fehlermeldung sieht, statt dass der Server abstürzt.
  • HA_URL und HA_TOKEN kommen aus Umgebungsvariablen, damit der Token nie im Code steht.

Wie Du Timeouts und Fehlerbehandlung bei API-Aufrufen grundsätzlich sauber löst, zeigt Robuste API-Aufrufe in Python: Timeouts, Retries, Logging. Für diesen Server reicht der feste Timeout von zehn Sekunden.

Wichtig: Ein stdio-Server darf nie etwas mit print() ausgeben. Die Standardausgabe gehört allein dem Protokoll, und jede zusätzliche Zeile dort zerschießt die Kommunikation. Nutze für Meldungen wie oben das Modul logging, das auf die Standardfehlerausgabe schreibt.

Schritt 3: Lokal testen mit dem MCP Inspector

Bevor Claude ins Spiel kommt, prüfst Du den Server mit dem offiziellen MCP Inspector. Er startet Deinen Server und zeigt im Browser, welche Tools und Ressourcen er anbietet. Ersetze im folgenden Befehl die Adresse durch die Deines Home Assistant und DEIN_TOKEN durch den eben erstellten Token:

Code
npx @modelcontextprotocol/inspector -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=DEIN_TOKEN uv run server.py

Die Option -e gibt die beiden Variablen an den Server weiter, alles nach den Optionen ist der Startbefehl. Der Inspector öffnet sich im Browser unter localhost. Klick auf Connect, öffne den Bereich Tools und lass Dir die Tools auflisten. Rufe dann sensoren_suchen mit einem Suchbegriff wie temperatur auf.

Klappt alles, siehst Du Zeilen wie diese:

Code
sensor.wohnzimmer_temperatur (Wohnzimmer Temperatur): 21.4 °C
sensor.balkon_temperatur (Balkon Temperatur): 6.8 °C

Teste auch einmal absichtlich einen Fehler, etwa sensor_lesen mit light.kueche. Der Server muss dann mit dem Hinweis auf erlaubte Entity-IDs antworten, statt die Anfrage an Home Assistant durchzureichen. Ich habe diese Prüfungen mit einem kleinen Python-Testclient aus dem SDK durchgespielt, auch die Fälle falscher Token (401), unbekannte Entität (404) und nicht erreichbares Home Assistant. Die Oberfläche des Inspectors selbst habe ich nicht durchgeklickt; Beschriftungen können je nach Version leicht abweichen.

Schritt 4: In Claude Code einbinden

Mit einem Befehl meldest Du den Server bei Claude Code an. Ersetze /Users/DEINNAME/ha-sensoren durch den absoluten Pfad Deines Projektordners, den Du im Ordner mit pwd herausfindest:

Code
claude mcp add --env HA_URL=http://homeassistant.local:8123 HA_TOKEN=DEIN_TOKEN --transport stdio --scope user ha-sensoren -- uv --directory /Users/DEINNAME/ha-sensoren run server.py

Hinter --env stehen beide Variablen, danach muss eine weitere Option wie --transport stdio folgen, sonst liest Claude Code den Servernamen als dritte Variable. --scope user macht den Server in allen Deinen Projekten verfügbar. Alles nach dem doppelten Bindestrich -- ist der Startbefehl, und uv --directory sorgt dafür, dass der Server im richtigen Ordner mit der richtigen Umgebung startet, egal wo Du Claude Code gerade aufrufst.

Prüfe danach mit claude mcp list, ob der Server als verbunden gemeldet wird. Starte dann Claude Code und frag zum Beispiel: „Wie warm ist es gerade im Wohnzimmer?” Claude ruft sensoren_suchen auf, findet den passenden Sensor und antwortet mit dem Wert. Die Ressource holst Du per @-Erwähnung in den Prompt: Tipp @ und wähle ha-sensoren:homeassistant://sensoren aus der Liste.

Schritt 5: In Claude Desktop einbinden

In Claude Desktop öffnest Du über das Claude-Menü in der Menüleiste (nicht im Fenster) die Einstellungen, wechselst links in den Bereich Developer beziehungsweise Entwickler und klickst auf Edit Config. Das öffnet oder erzeugt die Datei ~/Library/Application Support/Claude/claude_desktop_config.json. Trag dort den Server ein, wieder mit Deinem Pfad und Deinem Token:

Code
{
  "mcpServers": {
    "ha-sensoren": {
      "command": "/Users/DEINNAME/.local/bin/uv",
      "args": ["--directory", "/Users/DEINNAME/ha-sensoren", "run", "server.py"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "DEIN_TOKEN"
      }
    }
  }
}

Claude Desktop findet uv oft nicht, weil es den Suchpfad Deiner Shell nicht kennt. Trag deshalb bei command den vollständigen Pfad ein, den Dir which uv im Terminal ausgibt. Beende Claude Desktop danach komplett mit Cmd + Q und starte es neu. Klick danach unten links im Eingabefeld auf das Plus-Symbol, fahr mit der Maus auf Connectors und wähle Manage connectors. Dort steht ha-sensoren mit seinen beiden Tools.

Sicherheit: nur lesen, Eingaben prüfen

Ein MCP-Server führt Code mit Deinen Rechten aus, und das Modell entscheidet selbst, wann es ein Tool aufruft. Halte Dich deshalb an drei Regeln:

  1. Nur lesende Tools, solange es geht. Der Server oben kann nichts schalten, er nutzt ausschließlich GET-Anfragen. Die Markierung read_only_hint=True teilt das auch der Anwendung mit; Claude Code führt solche Tools zum Beispiel parallel aus. Eine Sicherung ist die Markierung aber nicht, die eigentliche Grenze ist Dein Code.
  2. Jede Eingabe prüfen. Die Entity-ID wird gegen ein festes Muster geprüft, bevor sie in eine URL wandert. So kann das Modell weder light.-Entitäten noch Pfade wie ../ einschleusen. Der Suchbegriff ist auf 50 Zeichen begrenzt, und die Ausgabe auf 50 Zeilen, damit eine große Installation nicht den Kontext flutet. Claude Code warnt ohnehin bei Tool-Antworten über 10.000 Tokens und begrenzt sie standardmäßig auf 25.000.
  3. Den Token schützen. Er hat dieselben Rechte wie das Home-Assistant-Konto, unter dem Du ihn erstellt hast, und kann über die API grundsätzlich auch Geräte schalten. Er gehört nie in ein Git-Repository und nie in eine geteilte .mcp.json. Brauchst Du ihn nicht mehr, löschst Du ihn im selben Menü, in dem Du ihn erstellt hast.

Wenn der Server nicht startet

Claude meldet „Failed to connect”. Starte den Server einmal von Hand mit uv --directory /Users/DEINNAME/ha-sensoren run server.py. Endet er mit KeyError: 'HA_URL', kommen die Umgebungsvariablen nicht an; prüf mit claude mcp get ha-sensoren, ob beide eingetragen sind. Läuft er ohne Ausgabe weiter, ist alles in Ordnung, denn er wartet auf Nachrichten. Beende ihn dann mit Strg + C.

ModuleNotFoundError: No module named 'mcp.server.fastmcp'. Der Code stammt aus einer Anleitung für das alte SDK. Ersetze den Import durch from mcp.server import MCPServer und FastMCP(...) durch MCPServer(...).

Das Tool antwortet mit 401. Der Token ist falsch, abgelaufen oder gelöscht. Erstelle einen neuen und trag ihn neu ein: in Claude Code mit claude mcp remove ha-sensoren und erneutem claude mcp add, in Claude Desktop direkt in der JSON-Datei.

Claude Desktop zeigt den Server nicht. Prüfe die JSON-Datei auf ein fehlendes Komma und schau in die Protokolle unter ~/Library/Logs/Claude/. Die Datei mcp-server-ha-sensoren.log enthält alles, was Dein Server auf die Fehlerausgabe schreibt, auch die Meldungen aus logging.

Ausbauideen

Mit demselben Muster wird aus dem Beispiel schnell ein Werkzeug für Deinen Alltag. Ein Tool, das den Verlauf eines Sensors über /api/history/period liest, beantwortet Fragen wie „Wann war es heute am kältesten?”. Statt Home Assistant kann die Funktion genauso eine SQLite-Datenbank, eine Firmen-API oder eine Ordnerstruktur abfragen; nur ha_get ändert sich. Schaltende Tools solltest Du erst bauen, wenn Du die lesenden eine Weile benutzt hast, und dann mit einer festen Liste erlaubter Geräte statt freier Entity-IDs.

Wenn Claude in Deinem Haus etwas Unerwartetes feststellt, etwa eine Automation, die nicht reagiert hat, führt Home Assistant: Automation löst nicht aus, Fehlersuche mit den Traces zur Ursache.

Die Grundlagen zu Tools, Ressourcen und Transporten erklärt die offizielle Seite Build an MCP server, den Quellcode des SDK findest Du im Repository modelcontextprotocol/python-sdk, und alle Optionen von claude mcp beschreibt Anthropic in der Doku zu MCP in Claude Code.

Weiterlesen.