ロボ図鑑

SwitchBot プラグミニ（JP）を公式MCPでON/OFFする — 読み取りから照明1台の実物確認まで

公開: 2026-09-07

SwitchBot プラグミニ（JP・通常版W2001400）は2.4GHz Wi-Fiを内蔵し、SwitchBotハブを増設せず公式MCPから操作できる。本稿では、いきなり書き込み権限を渡さず、読取専用で対象を特定してから、手元で見える照明1台だけを明示的にON/OFFする。

手順とMCPパラメータは2026年9月7日にSwitchBot公式OpenAPI CLI v3.8.1のソースと公式OpenAPIを確認した。ロボ図鑑では実機を接続しておらず、以下のコマンドと設定は構文・契約だけを確認した未実測手順である。

0. 試験対象を固定する

使うのは本体または箱にW2001400とある通常版だけ。W2001401はHomeKit対応版で、この手順の評価対象から外す。OpenAPIの一覧では両方がPlug Mini (JP)と表示されるため、API上の名前だけで版を決めず、実物の型式を確認する。

最初の負荷は、手元で点灯と消灯を目視できる低消費電力の照明1台にする。照明本体のスイッチは、通電が戻れば点灯する位置へ合わせる。次の条件を満たさない機器は初回試験に使わない。

通常版は幅広プラグを使うため、N極対応コンセントかN極対応延長コードが必要である。

1. アプリだけで照明をON/OFFする

SwitchBotアプリを最新版にし、「＋」→「手動で追加」→「電源スイッチ」→「プラグミニ（JP）」を選ぶ。本体ボタンを2〜3秒長押しし、インジケーターが青く速く点滅したら2.4GHz Wi-Fiを設定する。

MCPへ進む前に、次の3点をアプリと実物で確認する。

この段階で動かない場合は、MCPではなく配線、照明側のスイッチ、Wi-Fi、アプリ登録を直す。

2. 公式CLIを入れ、OAuthで認証する

確認済みの版へ固定してCLIを入れる。auth loginはブラウザOAuthを開き、認証情報をOSキーチェーンへ保存する。トークンやシークレットをMCP設定、チャット、シェル履歴へ貼らない。

npm install -g @switchbot/[email protected]
switchbot auth login
switchbot doctor --json

doctorが認証やcatalog schemaのエラーを返したら、その状態で操作へ進まない。

3. MCPを読取専用で起動する

MCPクライアントのサーバー設定へ次の1件を追加する。--portを付けなければstdio接続で、待受ポートは開かない。

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

readonlyプロファイルにはlist_devicesとget_device_statusがあり、send_commandはない。MCPクライアントを再起動したら、まず一覧を読む。

{
  "tool": "list_devices",
  "arguments": {}
}

返ったdeviceListから次をすべて満たす1台だけを選び、deviceIdを控える。

同名が複数ある場合は名前で操作せず、対象のdeviceIdを固定する。続いて状態を読む。

{
  "tool": "get_device_status",
  "arguments": {
    "deviceId": "<対象のdeviceId>"
  }
}

deviceType、voltage、electricCurrent、versionなど、実際に返ったキーと値を保存する。公式のPlug Mini (JP)用GET表にはON/OFFを示すpowerが載っておらず、powerStateはWebhook欄にだけある一方、公式CLIカタログはGET候補へpowerを含めており、資料間で一致しない。electricityOfDayも機種別文書は使用時間（分）、CLIカタログは当日消費量（kWh）と説明が食い違う。weightの意味・単位も曖昧である。実値とアプリ表示を照合するまで、これら3項目を料金計算や自動判定の条件に使わない。

4. 標準プロファイルへ切り替え、送信内容だけ確認する

対象IDを実物と突合できたら、MCP設定のargsを標準プロファイルへ変える。標準プロファイルはv3.8.1で17ツールを持ち、send_commandを含む。

標準プロファイルのsend_commandは、同じSwitchBotアカウント内で公式MCPが扱える他のデバイスにも送信できる。以下のdeviceId固定はこの試験手順の運用上の制限で、MCP側のアクセス制御ではない。MCPクライアント側の都度承認などが有効かは環境ごとに異なり、本稿では強制機構として確認していない。

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

クライアントを再起動し、もう一度list_devicesを呼ぶ。これは対象の再確認に加え、dryRunが参照するCLI内キャッシュを作るためでもある。続いて、APIへ送らずturnOnの形だけを検査する。

{
  "tool": "send_command",
  "arguments": {
    "deviceId": "<対象のdeviceId>",
    "command": "turnOn",
    "dryRun": true
  }
}

結果のwouldSendが対象ID、turnOn、commandType: commandになっていることを読む。parameterは省略してよい。公式MCPは省略時にdefaultを送る。

5. ONを1回だけ送る

人が照明の前にいて、異常時にコードを抜ける状態で実行する。

{
  "tool": "send_command",
  "arguments": {
    "deviceId": "<対象のdeviceId>",
    "command": "turnOn",
    "idempotencyKey": "<今回の試験専用ID>-on"
  }
}

確認結果を3段に分ける。

  1. MCP/API層: ok: trueとSwitchBot APIの成功応答を受けたか
  2. プラグ層: SwitchBotアプリで対象プラグがONになったか
  3. 家電層: 手元の照明が実際に点灯したか

get_device_statusも再度読み、電流などが変化したかを補助記録にする。ただし、電流値だけで点灯を断定しない。API成功と物理結果を一つの「成功」にまとめない。

タイムアウトや応答不明のときは、そのまま再送しない。アプリ、プラグの表示、照明、状態取得を確認し、最初のコマンドが届いたかを判定してから次へ進む。

6. OFFを1回だけ送る

同じdeviceIdへ、反転命令のtoggleではなくturnOffを指定する。

{
  "tool": "send_command",
  "arguments": {
    "deviceId": "<対象のdeviceId>",
    "command": "turnOff",
    "idempotencyKey": "<今回の試験専用ID>-off"
  }
}

MCP/API層の成功、アプリ上のOFF、実物の消灯をもう一度分けて確認する。最後は照明が消えた状態で試験を終え、対象ID、実行時刻、応答、物理結果を残す。

完了判定

機種の評価と状態値の注意はSwitchBot プラグミニ（JP・通常版W2001400）の標本、HMAC署名でOpenAPIを直接扱う場合はSwitchBot API v1.1ガイド、評価尺度は/ratingを参照。

参考情報

いずれも2026年9月7日に実確認。

他のガイド