kwikset-mcp

一个 MCP 服务器，可以让 Claude 检查并控制 Kwikset Halo 系列智能门锁（Halo、Halo Keypad、Halo Touch、Halo Select / Select Plus）。

它是 aiokwikset 的一个轻量封装。aiokwikset 是 Kwikset 云端 API 的社区维护 Python 客户端，与 Home Assistant Kwikset 集成 使用的是同一个库。

重要说明： Kwikset 不发布也不正式支持此 API。aiokwikset 是通过逆向工程实现的，因此如果 Kwikset 在服务端改动任何内容，它可能会失效。这个服务器专门提供了一个 debug_api_surface 工具以及防御式查找，目的是让这类损坏更容易诊断和修复，而不是默默硬性失败。

这个服务器尚未针对真实账户或真实门锁进行端到端测试 —— 它是根据 aiokwikset 已发布的文档和 Home Assistant 集成的源码构建的，没有使用 Kwikset 凭据或真实物理门锁。请按下面的步骤操作，并把第一次 lock/unlock 调用当作冒烟测试；如果任何调用抛出 api_mismatch 错误，请把错误信息（以及 debug_api_surface 的输出）粘贴回 Claude，让它修复那一两个不匹配的方法名。

为什么登录是独立的一步

你的 Kwikset 密码绝不应该经过 LLM 对话。因此，认证会在一个普通终端里通过 auth_setup.py 一次性完成，并且只会在本地保存生成的令牌（绝不会保存密码）。MCP 服务器会读取并静默刷新这些令牌——它绝不会向 Claude 索要密码，也不会通过 Claude 向你索要密码。

Related MCP server: Seam MCP Server

设置

1. 安装依赖（Python 3.10+）：

   cd kwikset-mcp
   python3 -m venv .venv

   激活虚拟环境——具体命令取决于你的 shell：

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

   # Windows PowerShell
   .venv\Scripts\Activate.ps1

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

   当你的命令提示符出现 (.venv) 前缀时，就表示激活成功了。如果 PowerShell 拒绝运行该脚本（提示 running scripts is disabled on this system），请先运行 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass，然后再重试激活命令。

   接着，在虚拟环境激活的状态下执行：

   pip install -e .

2. 登录一次。 凭据可以通过两种方式提供，按以下顺序检查：

   # 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

   第二种方式，即先设置环境变量，比上面的 --password 参数更推荐（因为命令行中的密码通过 ps aux / Task Manager 可以对其他进程可见，而且会留在 shell 历史记录中）——不过语法因 shell 而异：

   # 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

   如果你的账户启用了 MFA（多因素认证），系统会提示你输入验证码（也可以用 --mfa-code / $KWIKSET_MFA_CODE 提前传入）。无论哪种方式，这一步都会写入 ~/.kwikset-mcp/tokens.json（仅当前用户可读/写），并且之后不会再碰你的密码——MCP 服务器只读取和刷新已保存的令牌。

3. 让 Claude 指向这个服务器。

   对于 Claude Code，在项目目录下执行：

   # 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

   对于 Claude Desktop，请把以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）中，并将路径替换为本目录 .venv 的绝对路径：

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

   在 Windows 上，command 应指向 C:\\absolute\\path\\to\\kwikset-mcp\\.venv\\Scripts\\python.exe（因为是 JSON，所以使用双反斜杠）。

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

4. 试一下。 向 Claude 提出类似“列出我的 Kwikset 门锁”或“前门锁了吗？”的问题——它应该调用 list_locks / get_lock_status。解锁需要明确的请求，因为 unlock_door 只有在调用时带 confirm=true 才会执行，而 Claude 只会在你明确提出要解锁该门锁时才这样做。

工具一览

重新认证

如果令牌过期且无法静默刷新（例如 Kwikset 密码被修改，或者 MFA 被重置），工具调用会返回 auth_required 错误并附带说明——只需重新运行 python auth_setup.py 即可。

文件

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