kwikset-mcp

一个 MCP 服务器，让 Claude 可以查看和控制 Kwikset Halo 家族智能锁（Halo、Halo Keypad、Halo Touch、Halo Select / Select Plus）。

这是对早期 Python 版本的 Node.js 重写，用于避免 Windows 上 Python 特有的设置麻烦（缺少解释器、virtualenv 激活、PATH 别名）。Node.js 没有 aiokwikset（第一个版本所依赖的 Python 库）的精确对等物，因此这个版本直接与 Kwikset 的云 API 通信：使用 AWS Cognito 进行登录，外加一个用于 homes/devices/lock/unlock 的小型 REST API。

API 细节的来源： Kwikset 并不提供官方 API。本服务器使用的 Cognito pool/client ID、API 主机和 REST 路径，均来自已发布、采用 Apache-2.0 许可的 homebridge-kwikset-halo 源代码（一个社区 Homebridge 插件，适用于这些锁），该插件又转而感谢 aiokwikset 首先记录这些 API。具体细节请看 src/const.js 和 src/cognito.js 中的注释。本服务器不受 Kwikset 官方支持；如果他们改了服务端，可能会失效。

测试状态： 该服务器中的每一部分逻辑——Cognito 登录流程（包括两步手机验证挑战）、令牌刷新和持久化、REST 字段映射、unlock_door 的确认保护，以及每个 MCP 工具的端到端行为——都已用模拟 AWS Cognito、Kwikset REST API 和 MCP SDK 的手写 mock 进行测试，并且全部通过。此处无法测试的是调用真实的 Kwikset 服务，因为这需要一个真实账户和一把实体锁。把你第一次调用 list_locks 当作真正的冒烟测试——如果它彻底失败（不只是某个字段显示 null），那么 pool/host 常量可能已过时；如果某个工具返回 null，请运行 debug_raw_devices 查看真实字段名，并与 src/kwikset-client.js 对照。

为什么要单独登录

你的 Kwikset 密码绝不应经过 LLM 对话。因此，身份验证只需在普通终端中通过 auth-setup.js 执行一次，并且它只在本地保存生成的会话令牌（绝不保存密码）。MCP 服务器会在每次连接时读取并静默刷新这些令牌——它绝不向 Claude 请求你的密码，也不借助 Claude 向你索要密码。

Related MCP server: Lutron Caseta MCP Server

安装

1. 安装 Node.js（18+），如果还没有安装：nodejs.org —— 获取 LTS 安装程序。用以下命令验证：

   node --version

2. 安装依赖，请在此文件夹内运行：

   npm install

3. 登录一次。 凭据可以按三种方式提供，按以下顺序检查：

   # 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

   如果你的账户需要电话验证，系统会提示你输入 Kwikset 通过短信发送给你的验证码（或者直接用 --mfa-code 或 $KWIKSET_MFA_CODE 提前传入）。这会写入 ~/.kwikset-mcp/tokens.json（仅文件所有者可读/写），并且此步骤之后绝不会再使用你的密码。

4. 让 Claude 连接到该服务器。

   对于 Claude Code，请在此项目目录下运行：

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

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

   对于 Claude Desktop，请将此内容添加到你的 claude_desktop_config.json（Settings → Developer → Edit Config），并将路径替换为本文件夹中 src/server.js 的绝对路径：

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

   在 Windows 上，请在 JSON 路径中使用双反斜杠，例如 "C:\Users\you\kwikset-mcp\src\server.js"。

   然后重启 Claude 客户端，让它启用新的服务器。

5. 试一试。 问 Claude 类似“列出我的 Kwikset 门锁”或“前门锁上了吗？”的问题——它应当调用 list_locks / get_lock_status。解锁需要你明确要求，因为 unlock_door 只有在使用 confirm=true 时才执行操作，而 Claude 只会在你明确要求解除某扇门的锁时才会这样做。

暴露的工具

重新认证

如果令牌过期且无法静默刷新（例如 Kwikset 密码已更改，或 2FA 已重置），工具调用将返回 auth_required 错误，并附带提示——只需重新运行 node auth-setup.js。

文件

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