kwikset-mcp

Un servidor MCP que permite a Claude consultar y controlar las cerraduras inteligentes de Kwikset de la familia Halo (Halo, Halo Keypad, Halo Touch, Halo Select / Select Plus).

Esta es una reescritura en Node.js de una versión anterior en Python, elegida para evitar las fricciones de configuración específicas de Python en Windows (intérprete ausente, activación de virtualenv, alias de PATH). Node no tiene un equivalente exacto de aiokwikset (la librería Python de la que dependía la primera versión), así que esta versión habla directamente con la API en la nube de Kwikset: AWS Cognito para el inicio de sesión y una pequeña API REST para casas/dispositivos/bloquear/desbloquear.

De dónde salen los detalles de la API: Kwikset no publica una API oficial. Los IDs de pool/cliente de Cognito, el host de la API y las rutas REST que usa este servidor se extrajeron del código fuente publicado, con licencia Apache-2.0, de homebridge-kwikset-halo (un plugin comunitario de Homebridge para estas mismas cerraduras), que a su vez da crédito a aiokwikset por haberlos documentado por primera vez. Consulta los comentarios de src/const.js y src/cognito.js para más detalles. Esto no cuenta con soporte oficial de Kwikset y podría romperse si cambian algo en el lado del servidor.

Estado de las pruebas: toda la lógica de este servidor — el flujo de inicio de sesión de Cognito (incluido el desafío de verificación telefónica en dos pasos), la renovación de tokens, la persistencia de tokens, el mapeo de campos de la API REST, la protección de confirmación de unlock_door y todas las herramientas MCP de principio a fin — se probó contra simulacros escritos a mano que representan a AWS Cognito, la API REST de Kwikset y el SDK MCP, y todo pasa. Lo que no se ha podido probar aquí es llamar al servicio real de Kwikset, porque se necesita una cuenta real y una cerradura física. Considera tu primera llamada a list_locks como la prueba de humo real; si falla por completo (no solo un campo que muestre null), es posible que las constantes de pool/host estén desactualizadas; si una herramienta devuelve null, ejecuta debug_raw_devices para ver los nombres de campo reales y compáralos con src/kwikset-client.js.

Por qué el inicio de sesión es un paso aparte

Tu contraseña de Kwikset nunca debería pasar por una conversación con un LLM. Por eso la autenticación ocurre una sola vez, en un terminal normal, mediante auth-setup.js, que guarda localmente solo los tokens resultantes (nunca la contraseña). El servidor MCP lee y actualiza silenciosamente esos tokens en cada conexión — nunca le pide tu contraseña a Claude, ni a ti a través de Claude.

Related MCP server: Lutron Caseta MCP Server

Configuración

1. Instala Node.js (18+) si no lo tienes: nodejs.org — descarga el instalador LTS. Verifícalo con:

   node --version

2. Instala las dependencias, desde dentro de esta carpeta:

   npm install

3. Inicia sesión una vez. Las credenciales se pueden dar de tres maneras, comprobadas en este orden:

   # 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

   Si tu cuenta requiere verificación telefónica, se te pedirá el código que Kwikset te envíe por texto (o puedes pasarlo de antemano con --mfa-code / $KWIKSET_MFA_CODE). Esto escribe ~/.kwikset-mcp/tokens.json (solo lectura/escritura del propietario) y no vuelve a tocar tu contraseña después de este paso.

4. Configura Claude para apuntar al servidor.

   Para Claude Code, desde este directorio de proyecto:

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

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

   Para Claude Desktop, añade esto a tu claude_desktop_config.json (Ajustes → Desarrollador → Editar configuración), sustituyendo la ruta absoluta por el src/server.js de esta carpeta:

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

   En Windows, usa doble barra invertida en la ruta JSON, por ejemplo "C:\\Users\\you\\kwiket-mcp\\src\\server.js".

   Después reinicia el cliente de Claude para que cargue el nuevo servidor.

5. Pruébalo. Pide a Claude algo como "lista" o "la puerta principal está bloqueada" — debería llamar a list_locks / get_lock_status. Desbloquear requiere una petición explícita, porque unlock_door no actúa salvo que se llame con confirm=true, y Claude solo hará eso si le pides claramente que desbloquee esa puerta.

Herramientas expuestas

| Herramienta | Descripción | | --------------------------------- --------------------------------------- | | list_locks | Todas las cerraduras de la cuenta, con estado, % de batería y casa | | get_lock_status(device_id) | Estado, batería, modelo y número de serie de una cerradura | | lock_door(device_id) | Bloquear una puerta | | unlock_door(device_id, confirm) | Desbloquear una puerta (requiere confirm=true) | | debug_raw_devices | Diagnóstico: JSON crudo, sin procesar, de casas/dispositivos de la API de Kwikset |

Reautenticación

Si los tokens caducan y no se pueden actualizar en silencio (por ejemplo, se cambió la contraseña de Kwikset o se restableció la 2FA), las llamadas a las herramientas devolverán un error auth_required con instrucciones — solo tienes que volver a ejecutar node auth-setup.js.

Archivos

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