kwikset-mcp

Kwikset Halo ファミリーのスマートロック（Halo、Halo Keypad、Halo Touch、Halo Select / Select Plus）を Clade が確認・操作できるようにする MCP サーバーです。

aiokwikset の薄いラッパーです。KWikset のクラウド API 向けにコミュニティでメンテナンスされた Python クライアントで、Home Assistant Kwikset integration でも使われているものです。

重要: Kwikset はこの API を公開も公式サポートもしていません。aiokwikset はそれをリバースエンジニアリングしているため、Kwikset がサーバー側の仕様を変更すると壊れる可能性があります。このサーバーには debug_api_surface ツールと防御的な参照処理が含まれており、そうした破損が静かに致命的な失敗になるのではなく、診断・修正しやすくなっています。

実際のアカウントやロックを使ったエンドツーエンドのテストは未実施です —Kwikset の認証情報や実機のスマートロックにアクセスできないまま、aiokwikset の公開ドキュメントと Home Assistant インテグレーションのソースから構築したものです。以下の手順を実行し、最初の lock/unlock 呼び出しをスモークテストとして扱ってください。api_mismatch エラーが発生した場合は、その内容（およびデバッグ用の debug_api_surface 出力）を Clude に貼り付けて、一致しないメソッド名を1〜2つ修正してもらってください。

ログインを別ステップにする理由

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

   仮想環境を有効にします。コマンドはシェルよって異ります:

   # 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 が「このシステムではスクリプトがの実行が無効になっています」というメッセージを表示して実行を拒否するし場合、先に Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass を実行してから、アクティブ化のコマドを再実行してくだ在。

   次に、venv を有効にしたまま:

   pip install -e .

2. ログインを一度だけします。 認証情報は、次の3つの方法で指定でき、以下の順にチェックされます:

   # 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

   オプション2（環境変数を先に設定する方法）は、上記の --password フラグより推奨されます。コマンドラインのパスワードは ps aux や Task Manager を介し他のプロセスから見える可能性があり、シェル履歴に残るためです。ただし、その構えはシェル別です:

   # 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_ock_status が呼び出されるはずです。解錠操作は、unlock_door が confirm=true 付きで呼ばれない限りactionしません。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