kwikset-mcp

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

これは以前のPython版を Node.jsで書き直した ものです。Windowsで発生するPython固有のセットアップ上の面倒（インタープリター未設定、virtualenvの有効化、PATHエイリアス）を避けるために移行しました。最初のバージョンが依存していたaiokwikset（Pythonライブラリ）に相当するNode.jsのライブラリは存在しないため、このバージョンはKwiksetのクラウドAPIと直接通信します。ログインにはAWS Cognito、ホーム/デバイスの一覧とロック/ロック解除には小さなREST APIを使用します。

APIの詳細の入手元: Kwiksetは公式APIを公開していません。このサーバーが使用するCognitoプール/クライアントID、APIホスト、RESTパスは、同じロックに対応するコミュニティ製Homebridgeプラグインであるhomebridge-kwikset-haloのApache-2.0ライセンスで公開されたソースから抽出したものです。このプラグインは、aiokwiksetがそれらの情報を最初に文書化したことをクレジットしています。詳細はsrc/const.jsとsrc/cognito.jsのコメントを参照してください。これはKwiksetが公式にサポートするものではなく、サーバー側の仕様変更により動作しなくなる可能性があります。

テスト状況: このサーバーのロジックのすべて（2段階の電話番号確認チャレンジを含むCognitionログインフロー、トークンのリフレッシュと永続化、RESTのフィールドマッピング、unlock_doorの確認ガード、すべてのMCPツールのエンドツーエンド）は、AWS Cognito、KwiksetのREST API、MCP SDKの代わりとなる手書きのモックを使って検証し、すべて合格しています。ここでテストできなかったのは、実際のKwiksetサービスを呼び出すことです。実際のアカウントと物理的なロックが必要だからです。最初のlist_locks呼び出しを実際のスモークテストとして扱ってください。それが完全に失敗した場合（1つのフィールドがnullになるだけの場合ではなく）は、プール/ホストの定数が古くなっている可能性があります。ツールが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以上）をインストールします。まだ入っていない場合はNode.jsからLTS版を取得してください。確認コマンドは次のとおりです:

   node --version

2. 依存関係をインストールします。このフォルダ内で:

   npm install

3. 一度だけログインします。 認証情報は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からSMSで送られてくるコードを求められます（または、前もってで 指定することもできます）。これにより~/.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パス内ではdouble backslashを使用してください。例: "C:\\Users\\you\\kwikset-mcp\\src\\server.js" 。

   その後、Claudeクライアントを再起動して新しいサーバーを読み込ませてください。

5. 試してみます。 Claudeに「Kwiksetのロックを一覧表示して」とか「玄関のドアはロックされていますか？」と尋ねてみてください。list_locks / を呼ぶはずです。ロック解除には明示的な要求が必要です。unlock_doorはconfirm=trueで呼び出されない限り動作を拒否します。Claudeは、そのドアのロックを解除するとはっきり頼んだ場合にのみconfirm=trueを渡します。

利用できるツール

再認証

トークンが期限切れで自動リフレッシュできない場合（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