kwikset-mcp

An MCP server that lets Claude check and control Kwikset Halo-family smart locks (Halo, Halo Keypad, Halo Touch, Halo Select / Select Plus).

It's a thin wrapper around aiokwikset, the community-maintained Python client for Kwikset's cloud API — the same one used by the Home Assistant Kwikset integration.

Important: Kwikset does not publish or officially support this API. aiokwikset reverse-engineers it, so it can break if Kwikset changes something server-side. This server includes a debug_api_surface tool and defensive lookups specifically to make that kind of breakage easy to diagnose and patch rather than a silent hard failure.

This has not been tested end-to-end against a real account or lock — it was built from aiokwikset's published documentation and the Home Assistant integration's source, without access to Kwikset credentials or a physical lock. Run through the steps below and treat the first lock/ unlock call as a smoke test; if anything throws an api_mismatch error, paste it (and the debug_api_surface output) back to Claude to get the one or two mismatched method names fixed.

Why login is a separate step

Your Kwikset password should never pass through an LLM conversation. So authentication happens once, in a plain terminal, via auth_setup.py, which saves only the resulting session tokens locally (never the password). The MCP server reads and silently refreshes those tokens — it never asks Claude, or you via Claude, for your password.

Setup

1. Install dependencies (Python 3.10+):

   cd kwikset-mcp
   python3 -m venv .venv
   

   Activate the virtual environment — the command depends on your 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
   

   You'll know it worked when your prompt gets a (.venv) prefix. If PowerShell refuses to run the script ("running scripts is disabled on this system"), run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass first, then retry the activation command.

   Then, with the venv active:

   pip install -e .
   

2. Log in once. Credentials can be given three ways, checked in this order:

   # 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, setting environment variables first, is preferred over the --password flag above (a command-line password is visible to other processes via ps aux/Task Manager and lands in shell history) — but the syntax is shell-specific:

   # 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
   

   If your account has MFA enabled you'll be prompted for the code (or pass one up front with --mfa-code / $KWIKSET_MFA_CODE). Either way this writes ~/.kwikset-mcp/tokens.json (owner-read/write only) and never touches your password again after this step — the MCP server only ever reads and refreshes the saved token.

3. Point Claude at the server.

   For Claude Code, from this project directory:

   # 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
   

   For Claude Desktop, add this to your claude_desktop_config.json (Settings → Developer → Edit Config), substituting the absolute path to this directory's .venv:

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

   On Windows, command should point at C:\\absolute\\path\\to\\kwikset-mcp\\.venv\\Scripts\\python.exe (use double backslashes, since this is JSON).

   Then restart the Claude client so it picks up the new server.

4. Try it. Ask Claude something like "list my Kwikset locks" or "is the front door locked?" — it should call list_locks / get_lock_status. Unlocking requires an explicit ask, since unlock_door refuses to act unless called with confirm=true, which Claude will only do when you've clearly asked it to unlock that door.

Tools exposed

Re-authenticating

If tokens expire and can't silently refresh (e.g. the Kwikset password was changed, or MFA was reset), tool calls will return an auth_required error with instructions — just re-run python auth_setup.py.

Files

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