SwitchBot カーテン3をAIから扱うとき、最初に確認するのは「開いたか」ではなく、対象の型式・デバイスID・較正状態・現在位置である。本稿はSwitchBot公式OpenAPI、公式BLE仕様、公式OpenAPI CLI v3.8.1を2026年9月14日に確認して整理した。実機への接続、校正、位置指令は行っていない。読者が実機で試す場合も、まず状態取得だけを通してから、1台に限定した明示操作へ進める。
0. 動かす前の境界
カーテン3はレール上を動くモーター機器である。人・ペット・家具がカーテンの走行範囲に入らないこと、手で直ちに停止できることを先に確かめる。複数台を同時に操作せず、未確認の自動校正も実行しない。APIの成功レスポンスだけで、実際のカーテンが所定位置に着いたとは扱わない。
1. 公式MCPを読み取り専用から始める
OpenWonderLabsの公式OpenAPI CLI v3.8.1には、MCPサーバーを起動するswitchbot mcp serveがある。公式Agent Guideでは、list_devicesとget_device_statusを読み取り用、send_commandを操作用として分けている。まずlist_devicesで一覧を取り、名前だけでなくdeviceType、Cloud Serviceの有効状態、親ハブ、デバイスIDを照合する。
switchbot mcp serve
MCPクライアント側では、最初に次の順序で読む。
list_devicesでCurtain 3の候補を列挙するdeviceTypeが公式資料のCurtain3に一致するか確認するenableCloudService、hubDeviceId、名前、対象レールを照合するget_device_statusで対象1台の状態を取得する
CLIのカタログはCurtain 3の別名としてCurtain3とCurtain 3を持つ。名前の表示揺れで別機種と判断せず、一覧の型式と対象IDを固定する。エージェントへ複数台の候補をそのまま渡さず、運用側で許可対象を1台に絞る。IDを固定しても、それ自体がMCPのアクセス制御になるわけではない。
2. 状態のどこを見るか
公式OpenAPIのCurtain 3の状態には、次の項目がある。
calibrate: 開位置と閉位置の校正が済んでいるかmoving: 現在移動中かslidePosition: 校正した開位置と閉位置の間を何%進んだかbattery: 4段階に丸められた電池残量version: 現在のファームウェアバージョンgroup: 別のCurtainとペア/グループになっているか
slidePositionは部屋の絶対座標でも、残り距離でもない。校正が済んでいない状態では、位置の数値を完了判定へ使わない。移動中はmovingを併読し、返ってきた位置と実際の幕の位置を別々に確認する。
3. ハブとCloud Serviceを確認する
公式製品ページは、音声操作などのサードパーティーサービス利用にSwitchBotハブシリーズが必要だと案内している。Cloud APIや公式MCPを使う場合は、アプリ側でCloud Serviceが有効か、対象カーテンに親ハブがあるかを実際の構成で確認する。BLE仕様が公開されていることだけから、Cloud Serviceやハブが不要になるとは言えない。
カーテンのレールはU型、ポールタイプ、I型で扱いが分かれ、片開きと両開きも構成が異なる。左右を別々の機器で動かす場合も、最初の確認対象は1台に限定する。カーテン2や旧Curtainの仕様をカーテン3へ横展開しない。
4. 位置指定は明示値で1回だけ送る
公式OpenAPIのsetPositionは、0,ff,80のようにインデックス、モード、位置を渡す。モードは0がPerformance、1がSilent、ffが既定。位置は0〜100で、0が開、100が閉である。turnOnは開位置、turnOffは閉位置、pauseは停止に相当する。
CLIの公式Agent Guideには、位置指定を名前付き引数へ展開する形式もある。
switchbot devices expand <CURTAIN_DEVICE_ID> setPosition --position 50 --mode silent
これはコマンドを送信する例であり、実機で実行していない。AIから操作を許可する場合も、対象ID・位置範囲・速度/モード・実行時間・停止条件を別の固定ルールへ置く。現在位置を読まずにtoggle相当の反転動作へ進まず、開く/閉じる/50%のように意図を明示する。
操作後の判定を3つに分ける。
- APIまたはMCPが返した受理結果
- 再取得した
moving、slidePosition、calibrateなどの状態 - 実際のカーテンが指定位置へ着いたか
1だけでは機械の到達を証明できない。状態取得が止まった、offline相当のエラーが出た、または人・物が走行範囲へ入った場合は追加命令を送らず、手元の停止手段を使う。
5. BLEは別経路として扱う
SwitchBot公式BLE APIには、Curtain 3のサービスUUID、基本情報、較正、電池、移動状態、位置の読み取りが定義されている。これは端末から直接BLE接続する経路であり、Cloud APIのenableCloudServiceや公式MCPの認証を省略できるという意味ではない。BLEの接続・切断・再接続は、このサイトでは実機未検証である。
6. AIへ渡す範囲
最初に公開するツールはlist_devices、get_device_status、describe_deviceなどの読み取り面に限定する。操作を開ける場合は、対象1台のIDを固定し、setPositionとpauseなど許可した命令だけを別の安全層で検査する。全台一括操作、未確認の校正、停止手段のない自動運転をAIへ渡さない。
公式資料上は位置取得、位置指定、停止、Webhookによる変更通知まで揃っている。しかし、実機を接続していないこの標本では、APIの仕様が実際のレール、カーテン重量、設置状態で成立することまでは確認していない。verifiedの印は付けず、仕様上できることと実測したことを分けて読む。
カーテン3の標本には、価格・型式・Cloud API・公式MCP・BLEの境界をまとめている。ボット、ハブ2、プラグミニは対象となる状態と操作が違うため、同じ命令表を流用しない。