ロボ図鑑

SwitchBot API v1.1をAIから使う — 公式CLI・MCP・OAuthと署名の実務ガイド

公開: 2026-08-09 / 更新: 2026-10-12

SwitchBotには公式クラウドAPI v1.1と、MCPサーバーを内蔵した公式CLIがある。AIエージェントにつなぐなら、まず公式CLIのブラウザOAuthとMCPを使うと、署名生成やトークンの手作業を減らせる。この記事はOpenWonderLabsの公式CLI README・Agent Guide、API v1.1、BLE APIを2026年10月12日に確認して整理した。ロボ図鑑では実機接続やコマンド実行をしていない。ハブ本体の対応範囲はSwitchBot ハブ2の標本を参照。

公式CLIからMCPへつなぐ

公式CLIはNode.js 18以降で動作する。インストール後、ブラウザOAuthでSwitchBotにログインし、CLI側の認証状態を確認する。

npm install -g @switchbot/openapi-cli
switchbot auth login
switchbot doctor --json

auth loginはブラウザを開いて認証し、資格情報をOSキーチェーンへ保存する。Developer OptionsからToken/Secretをコピーする作業は、ブラウザOAuthを使うときには不要だ。MCPクライアントへ登録する場合は、ローカルのstdio接続でswitchbot mcp serveを起動する。

{
  "mcpServers": {
    "switchbot": {
      "command": "switchbot",
      "args": ["mcp", "serve"]
    }
  }
}

READMEはmcp serveの標準セットを17ツール、--tools allを28ツールと説明する。Agent Guideは「Available tools (28)」として全ツールを示し、その表には25ツール、3つのdeprecated aliasは別節に置いている。CLI実装の--toolsプロファイルはreadonly 14、default 17、all 28に分かれる。読み取り専用で公開するならswitchbot mcp serve --tools readonlyを指定する。既定の17ツールにはsend_command・run_scene・plan_runなどの操作系が含まれるため、標準設定を読み取り専用と見なさない。READMEのGemini拡張の説明にも、14 read-only・17 default・28 allという別の記載がある(CLI README、Agent Guide、CLI tool profiles、MCP serve options)。

Agent Guideではsend_commandなどを操作として分類し、Smart Lockの解錠やGarage Doorの開放など、破壊的と指定された命令にはconfirm: trueが必要としている。標準プロファイルでは破壊的命令を直接実行せず、保存・レビュー・承認後に実行する経路が既定だ。どのMCPクライアントを使う場合でも、操作権限を絞るときは公開するツールを確認する。

TokenとSecretを使う場合

ブラウザOAuthを使わず、APIのTokenとSecret Keyを設定する方法もある。Secret Keyを取得するには、公式API資料の注記どおりアプリV6.14以降が必要。公式CLI READMEは、アプリのプロフィール→Preferences→App Versionを10回タップし、Preferencesへ戻ってDeveloper Optionsを開き、TokenとSecret Keyをコピーする手順を案内している。API v1.1資料は、アプリV9.0以降ではProfile→Preferences→About→App Version、V9.0未満ではProfile→Preferences→App Versionを10回タップする経路を説明する。Aboutの有無は公式資料間で異なるため、アプリのバージョンと画面表示に沿ってDeveloper Optionsを開く。

switchbot config set-token <token> <secret>

CLIが資格情報を探す優先順は、環境変数、OSキーチェーン、~/.switchbot/config.json。SWITCHBOT_TOKENとSWITCHBOT_SECRETが設定されていれば、環境変数がキーチェーンより優先される。TokenやSecretを記事・URL・MCP設定例・チャットへ書かず、保存先のアクセス権を管理する(CLI README、API v1.1資料)。

API v1.1の署名

CLIを介さずREST APIを実装する場合、v1.1ではTokenに加えてSecret Keyから作る署名が必要になる。リクエストには次の値をヘッダーで渡す。

公式の説明文は署名入力をtoken+tとし大文字化を指示する一方、Python 3・JavaScript・Goの例はnonceも含むtoken+t+nonceをHMAC-SHA256へ渡す。Python 3とJavaScriptはBase64出力をそのまま使い、Go例はBase64出力にstrings.ToUpperを適用する。説明文とサンプルで入力と大文字化の両方が食い違い、実際にAPIが受理する表記は未検証なので、どちらが正しいかを推測で補わない(公式の署名説明とPython 3・JavaScript・Go例)。

デバイス一覧・状態・操作の境界

公式APIのGET /v1.1/devicesでデバイス一覧を読み、機種ごとの対応表でdeviceIdと機能を確認する。状態取得はGET /v1.1/devices/{deviceId}/status、操作はPOST /v1.1/devices/{deviceId}/commands。操作できるコマンドと必須パラメータは機種ごとに異なるため、対象機種の対応表と公式CLIカタログを確認する。任意のdeviceIdへ任意のcommandを送るだけの自作例は載せない。

ハブ2本体は公式対応表で一覧・状態・Webhookに対応するが、本体自身へのCommandはない。ハブ2に登録した赤外線機器は仮想リモコンとして、ハブ経由のBLE機器は機種ごとの対応範囲で扱う。ハブ経由で操作できることと、ハブ本体をコマンド対象にできることは分ける(SwitchBot API v1.1 対応表、SwitchBot BLE API)。

公式APIには1アカウントあたり1日10,000リクエストの上限がある。公式API資料の英語注記はAPIを個人利用向けとし商用・大規模利用を禁止と記す一方、日本語注記では商用製品・サービスへの統合や数千回規模の呼び出しを予定する場合、事前相談してEnterprise APIの条件を確認するよう案内している。該当する利用条件は公式窓口で確認する。状態を頻繁に読む場合は、ポーリング間隔とWebhookの利用可否を確認する。赤外線家電ではAPIが命令を受け付けた応答と、家電の実際の状態が同じとは限らない。機種に状態取得が用意されているか、別のセンサーで結果を確認できるかを確かめる(SwitchBot API v1.1)。

公開済みレシピ

機種ごとの接続手順と操作範囲は、公開済みのレシピで確認できる。

参考資料（2026年10月12日確認）

他のガイド