kwikset-mcp

Ein MCP-Server, der Claude Smart-Schlösser der Kwikset-Halo-Familie (Halo, Halo Keypad, Halo Touch, Halo Select / Select Plus) abfragen und steuern lässt.

Er ist ein dünner Wrapper um aiokwikset, den von der Community gepflegten Python-Client für die Cloud-API von Kwikset – denselben, den auch die Home Assistant Kwikset-Integration verwendet.

Wichtig: Kwikset veröffentlicht diese API nicht und unterstützt sie offiziell nicht. aiokwikset rekonstruiert sie per Reverse Engineering, sodass sie brechen kann, falls Kwikset serverseitig etwas ändert. Dieser Server enthält ein debug_api_surface-Tool und defensive Lookups, damit solche Störungen leicht zu diagnostizieren und zu beheben sind, statt still und hart zu scheitern.

Dieser Server wurde nicht End-to-End gegen ein echtes Konto oder ein echtes Schloss getestet – er wurde anhand der veröffentlichten Doku von aiokwikset und des Quellcodes der Home Assistant-Integration erstellt, ohne Zugriff auf Kwikset-Anmeldedaten oder ein physisches Schloss. Arbeite die folgenden Schritte durch und behandle den ersten lock/unlock-Aufruf als Smoke-Test; falls etwas einen api_mismatch-Fehler auswirft, setze ihn (sowie die Ausgabe von debug_api_surface) zurück in Claude ein, damit die ein oder zwei nicht übereinstimmenden Methodennamen korrigiert werden können.

Warum die Anmeldung ein separater Schritt ist

Dein Kwikset-Passwort sollte niemals durch ein LLM-Chatgespräch laufen. Deshalb erfolgt die Authentifizierung einmalig, in einem einfachen Terminal, über auth_setup.py, das nur die resultierenden Session-Tokens lokal speichert – niemals das Passwort. Der MCP-Server liest diese Tokens und erneuert sie stillschweigend – er fragt nie Claude und dich nicht dazu über Claude Code nach deinem Passwort.

Related MCP server: Seam MCP Server

Einrichtung

1. Abhängigkeiten installieren (Python 3.10+):

cd kwikset-mcp
python3 -m venv .venv

Aktiviere die virtuelle Umgebung – der Befehl hängt von deiner Shell ab:

# macOS / Linux (bash or zsh)
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

:: Windows Command Prompt (cmd.exe)
.venv\Scripts\activate.bat

Du erkennst den Erfolg daran, dass dein Prompt ein (.venv)-Präfix bekommt. Falls PowerShell das Skript nicht ausführen möchte („running scripts is disabled on this system"), führe zuerst Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass aus, dann wiederhole den Aktivierungsbefehl.

Danach, während der Umgebung aktiv ist:

pip install -e .

2. Einmal anmelden. Die Anmeldedaten können auf drei Arten angegeben werden, die in dieser Reihenfolge geprüft werden:

# 1. Command-line flags (any OS/shell)
python auth_setup.py --email you@example.com --password 'hunter2'

# 3. Interactive prompt (any OS/shell; default if nothing else is given)
python auth_setup.py

Option 2 – zuerst Umgebungsvariablen zu setzen – ist dem --password-Flag oben vorzuziehen (ein Kommandozeilen-Passwort ist über ps aux/Task-Manager für andere Prozesse sichtbar und landet in der Shell-Historie) – die Syntax ist allerdings shell-spezifisch:

# macOS / Linux (bash or zsh)
KWIKSET_EMAIL=you@example.com KWIKSET_PASSWORD='hunter2' python auth_setup.py

# Windows PowerShell
$env:KWIKSET_EMAIL = "you@example.com"
$env:KWIKSET_PASSWORD = "hunter2"
python auth_setup.py

Wenn für dein Konto MFA aktiviert ist, wirst du zur Eingabe des Codes aufgefordert (alternativ übergib ihn gleich mit --mfa-code bzw. $KWIKSET_MFA_CODE). In jedem Fall werden ~/.kwikset-mcp/tokens.json (nur Besitzer-Lese-/Schreibrechte) geschrieben und dein Passwort wird nach diesem Schritt nie wieder angefasst – der MCP-Server liest und erneuert ausschließlich das gespeicherte Token.

3. Richte Claude Code oder Claude Desktop auf den Server aus.

   Für Claude Code, aus diesem Projektverzeichnis:

# macOS / Linux
claude mcp add kwikset -- "$(pwd)/.venv/bin/python" -m kwikset_mcp.server

# Windows PowerShell
claude mcp add kwikset -- "$PWD\.venv\Scripts\python.exe" -m kwikset_mcp.server

Für Claude Desktop, füge dies zu deiner claude_desktop_config.json hinzu (Settings → Developer → Edit Config) und setze dabei den absoluten Pfad zum .venv in diesem Verzeichnis ein:

{
  "mcpServers": {
    "kwikset": {
      "command": "/absolute/path/to/kwikset-mcp/.venv/bin/python",
      "args": ["-m", "kwikset_mcp.server"]
    }
  }
}

Unter Windows sollte command auf C:\\absolute\\ppath\\to\\kwikset-mcp\\.venv\\Scripts\\python.exe zeigen (mit doppelten Backslashes, da es sich um JSON handelt).

Die Client-Anwendung neu starten, damit der Claude den neuen Server erkennt.

4. Verfahren ausprobieren. Frage Claude zum Beispiel „list my Kwikset locks" oder „is the front door locked?" – er sollte list_locks / get_lock_status aufrufen. Das Entsperren erfordert eine explizite Aufforderung, da unlock_door sich weigert zu handeln, solange es nicht mit confirm=true aufgerufen wird – und Claude Code setzt confirm=true nur dann, wenn du eindeutig darum bittest, diese Tür zu öffnen.

Verfügbare Tools

Erneute Anmeldung

Wenn Tokens ablaufen und sich nicht leise erneuern lassen (z. B. weil das Passwort geändert wurde oder die MFA zurückgesetzt wurde), liefern Tool-Aufrufe einen auth_required-Fehler mit Anweisungen zurück – einfach python auth_setup.py erneut ausführen.

Dateien

kwikset-mcp/
├── auth_setup.py           # run once, by hand, to log in
├── src/kwikset_mcp/
│   ├── auth.py              # local token file read/write
│   ├── client.py            # aiokwikset wrapper (locks, status, etc.)
│   └── server.py            # FastMCP server + tool definitions
├── pyproject.toml
└── requirements.txt