kwikset-mcp

Ein MCP-Server, mit dem Claude die Smart-Locks der Kwikset-Halo-Familie prüfen und steuern kann (Halo, Halo Keypad, Halo Touch, Halo Select / Select Plus).

Dies ist eine Node.js-Implementierung einer früheren Python-Version, gewechselt wurde, um pythonspezifischen Einrichtungsfreibwurf unter Windows zu vermeiden (fehlender Interpreter, virtualenv-Aktivierung, PATH-Aliasing). Node hat kein exaktes Äquivalent zu aiokwikset (der Python-Bibliothek, auf der die erste Version basierte); diese Version spricht daher direkt Kwiksets Cloud-API an: AWS Cognito für die Anmeldung, dazu eine kleine REST-API für homes/devices/Lock/Unlock.

Woher die API-Details stammen: Kwikset veröffentlicht keine offizielle API. Die Cognito-Pool-/Client-IDs, der API-Host und die REST-Pfade, die dieser Server verwendet, wurden aus dem veröffentlichten, unter Apache-2.0 lizenzierten Quellcode von homebridge-kwikset-halo extrahiert (ein Community-Homebridge-Plugin für genau diese Schlösser), das wiederum aiokwikset für die Erstdokumentation dieser Details würdigt. Details findest du in den Kommentaren in src/const.js und src/cognito.js. Dies ist nicht offiziell durch Kwikset unterstützt und könnte brechen, wenn Kwikset serverseitig etwas ändert.

Teststatus: Jedes Stück Logik auf diesem Server – der Cognito-Login-Ablauf (einschließlich der zweistufigen Telefonverifizierung-Herausforderung), Token-Refresh und Persistenz, das REST-Feld-Mapping, die unlock_door-Bestätigungssperre und jedes MCP-Tool Ende-zu-Ende – wurde gegen handgeschriebene Mocks geprüft, die für AWS Cognito, Kwiksets REST-API und das MCP-SDK stehen; und alles besteht. Was hier nicht getestet werden konnte, war der Aufruf des echten Kwikset-Dienstes, da dies ein echtes Konto und ein physisches Schloss erfordert. Behandle deine ersten list_locks-Aufruf als den echten Smoke-Test – wenn er komplett scheitert (nicht nur ein Feld mit null), sind die Pool-/Host-Konstanten möglicherweise veraltet; wenn ein Tool nulls liefert, führe debug_raw_devices aus, um die echten Feldnamen zu sehen, und vergleiche sie mit src/kwikset-client.js.

Warum die Anmeldung ein eigener Schritt ist

Dein Kwikset-Passwort sollte nie durch ein LLM-Gespräch laufen. Daher erfolgt die Authentifizierung genau einmal in einem schlichten Terminal über auth-setup.js, wobei nur die resultierende Session-Tokens lokal abgelegt werden – niemals das Passwort. Der MCP-Server liest diese Tokens bei jeder Verbindung und frischt sie unauffällig auf – er fragt nie Claude, oder dich über Claude, nach deinem Passwort.

Related MCP server: Lutron Caseta MCP Server

Einrichtung

1. Node.js installieren (18+), falls nicht vorhanden: nodejs.org – die LTS-Installer holen. Überprüfen mit:

   node --version

2. Abhängigkeiten installieren, innerhalb dieses Ordners:

   npm install

3. Einmalig anmelden. Anmeldeinformationen können auf drei Arten angegeben werden, die in dieser Reihenfolge geprüft werden:

   # 1. CLI flags (any OS/shell)
   node auth-setup.js --email you@example.com --password "hunter2"

   # 2. Environment variables (preferred over the flag above - a
   #    command-line password is visible to other processes/users on the
   #    machine and lands in shell history)
   
   # macOS / Linux
   KWIKSET_EMAIL=you@example.com KWIKSET_PASSWORD='hunter2' node auth-setup.js

   # Windows PowerShell
   $env:KWIKSET_EMAIL = "you@example.com"
   $env:KWIKSET_PASSWORD = "hunter2"
   node auth-setup.js

   # 3. Interactive prompt (any OS/shell; default if nothing else is given)
   node auth-setup.js

   Falls bei deinem Konto eine Telefonverifizierung erforderlich ist, wirst du nach dem Code zusätzlichen aufgefordert, den Kwikset dir per SMS sendet (oder du gibst ihn gleich mit --mfa-code / $KWIKSET_MFA_CODE an). Dabei wird ~/.kwikset-mcp/tokens.json erzeugt (nur Owner-Lese/Schreibrechte) und dein Passwort wird nach diesem Schritt nie wieder berührt.

4. Richte Claude auf den Server aus.

   Für Claude Code, von diesem Projektverzeichnis heraus:

   # macOS / Linux
   claude mcp add kwikset -- node "$(pwd)/src/server.js"

   # Windows PowerShell
   claude mcp add kwikset -- node "$PWD\src\server.js"

   Für Claude Desktop, füge diese Eintrag zu deiner claude_desktop_config.json hinzu (Einstellungen → Entwickler → Konfiguration bearbeiten), und setze den absoluten Pfad zu src/server.js aus dieenem Ordner ein:

   {
     "mcpServers": {
       "kwikset": {
         "command": "node",
         "args": ["/absolute/path/to/kwikset-mcp/src/server.js"]
       }
     }
   }

   Unter Windows verwendest du im JSON-Pfad doppelte Backslashes, z.?B. "C:\\Users\\you\\kwikset-mcp\\src\\server.js".

   Starte danach den Claude-Client neu, damit er den neuen Server übernimmt.

5. Einmalig ausprobieren. Frag Claude sowas wie „Liste meine Kwikset-Schlösser auf“ oder „Ist die Haustür verriegelt?“ – er sollte dann list_locks / get_lock_status aufrufen. Das Entsper erfordert eine ausdrückliche Aufforderung, denn unlock_door weigert sich, zu handeln, außer confirm=true wird übergegeben, und Claude macht das nur, wenn du es eindeutig hierum gebeten hast, diese betreffende Tür zu öffnen.

Tools

Erneute Authentifizierung

Wenn Tokens ablaufen und nicht leise aktualisiert werden können (z. B. weil das Kwikset-Passwort geändert wurde oder 2FA zurückgesetzt wurde), legeben Tool-Aufrufe einen auth_required-Fehler mit Anweisungen zurück – einfach node auth-setup.js erneut ausführen.

Dateien

kwikset-mcp/
├── auth-setup.js           # run once, by hand, to log in
├── src/
│   ├── const.js             # Cognito pool/client IDs, API host (see caveats above)
│   ├── auth.js               # local token file read/write
│   ├── cognito.js            # AWS Cognito login/refresh (amazon-cognito-identity-js)
│   ├── kwikset-client.js     # REST calls: homes, devices, lock/unlock
│   └── server.js             # MCP server + tool definitions
├── package.json
└── .gitignore