flipper-mcp-bridge

USB接続されたFlipper ZeroをMCPクライアント（Claude Code、互換ブリッジ経由のHome Assistantなど）向けのツールセットとして公開するMCPサーバー。v0ではIR（赤外線）に焦点を当てており、保存された.irファイルのリスト表示・解析、ボタンの再送、新しい信号のキャプチャが可能です。

Momentum firmware (mntm-008) でテスト済みです。同じCLI（ir tx, ir rx, storage *, loader *）を持つ最近のFlipperフォークであれば動作するはずです。

v0ツール

ツール	用途
`device_info`	Flipperの `device_info` 辞書（ファームウェア、ハードウェア、無線）を返す
`list_ir_files`	SDカード上のディレクトリ内の `.ir` ファイルをリスト表示する
`list_ir_buttons`	保存された `.ir` ファイルを解析し、そのボタンを返す
`send_ir_button`	保存された `.ir` ファイルから指定したボタンを送信する
`send_ir_signal`	MSBファーストの整数16進数（例: `NECext DF02 EE11`）で解析されたアドホックなIR信号を送信する
`list_universal_remotes`	ファームウェアで利用可能な内蔵ユニバーサルIRリモコン（ac, tv, fansなど）をリスト表示する
`list_universal_signals`	内蔵ユニバーサルリモコンの信号名をリスト表示する
`send_universal_signal`	内蔵ユニバーサルリモコンから指定した信号を送信する
`learn_ir_button`	FlipperをRXモードにし、次のリモコン操作をキャプチャして `.ir` ファイルに追記する

セットアップ（Windowsホスト、WSL2）

1. Flipper USBをWSLに転送する

Windowsに usbipd-win をインストールします：

winget install usbipd

次に（Windows PowerShellから）：

usbipd list                          # find the Flipper's BUSID
usbipd bind --busid <X-Y>            # one-time, admin PowerShell
usbipd attach --wsl --busid <X-Y>    # each replug / reboot

attach 後、FlipperはWSL上で /dev/ttyACM0 として認識されます。

2. WSLでシリアルアクセス権限を付与する

sudo usermod -aG dialout $USER

その後、グループを有効にするためにWSLを再起動します：

wsl.exe --shutdown

シェルを再起動します。groups に dialout が含まれているはずです。

3. 依存関係のインストール

リポジトリのルートから：

uv sync

4. 動作確認

uv run python scripts/smoketest_readonly.py

デバイス情報、/ext/infrared/ 以下のファイルリスト、および各 .ir ファイルの解析内容が表示されるはずです。

実行方法

MCP stdio（Claude Code、Cursorなど用）：

uv run flipper-mcp-bridge

HTTP REST API（Home Assistant、curl、スクリプト用）：

uv run flipper-mcp-bridge --http --port 8765

エンドポイント：

メソッド	パス	ボディ / クエリ
`GET`	`/health`	—
`GET`	`/device`	—
`GET`	`/ir/files`	`?dir=/ext/infrared`
`GET`	`/ir/buttons`	`?file=/ext/infrared/Remote.ir`
`POST`	`/ir/send-button`	`{"file": "...", "button": "..."}`
`POST`	`/ir/send-signal`	`{"protocol": "...", "address": "...", "command": "..."}`
`GET`	`/ir/universal/list`	`?remote=ac` (省略すると利用可能なリモコンをリスト表示)
`POST`	`/ir/universal/send`	`{"remote": "ac", "signal": "OFF"}`
`POST`	`/ir/learn`	`{"file": "...", "button": "...", "timeout_seconds": 30}`

Home Assistantとの統合

デプロイに関する注意：HAからの到達性

HAがブリッジに対してHTTPリクエストを送れる必要があります。以下の2つの簡単な構成がそのまま利用可能です：

ブリッジをHAと同じホストで実行する（Flipperを接続したPi/NUC/サーバー）。HAは http://127.0.0.1:8765 にアクセスします。これが最も簡単です。
LAN上の常時稼働Linuxホストでブリッジを実行する。--host 0.0.0.0 を付けて起動します（CLIで警告が表示されます。v1では認証がないため、信頼できるLAN内でのみ実行してください）。HAは http://HOST:8765 にアクセスします。

WSL2の注意点: WSL2はNATを使用するため、WSLのIPにはLAN上の他のホストから到達できません。WSL2内でブリッジを実行し、別のデバイス上のHAからアクセスさせるには、Windowsホスト側で netsh interface portproxy によるポート転送を行うか、Windowsホスト上で直接ブリッジを実行する必要があります（Python + pyserialはWindows上で問題なく動作します）。

設定

configuration.yaml に以下を記述します：

rest_command:
  flipper_humidifier_toggle:
    url: "http://FLIPPER_HOST:8765/ir/send-button"
    method: POST
    content_type: "application/json"
    payload: '{"file":"/ext/infrared/Remote.ir","button":"Humid"}'

  flipper_ac_off:
    url: "http://FLIPPER_HOST:8765/ir/universal/send"
    method: POST
    content_type: "application/json"
    payload: '{"remote":"ac","signal":"OFF"}'

次に、オートメーションやスクリプトで以下のように使用します：

action:
  - service: rest_command.flipper_humidifier_toggle

スイッチのようなエンティティにするには、同じ /ir/send-button エンドポイントを指定したRESTfulスイッチを使用してください（Flipper自体はデバイスの状態を公開しないため、状態はHA側で管理されます）。

ポートの選択

ブリッジは以下の優先順位でシリアルデバイスを選択します：

明示的な port= 引数（ライブラリ使用時のみ）
FLIPPER_PORT 環境変数
自動検出: USBメーカーが "Flipper Devices Inc."（またはVID:PID 0483:5740）である最初に見つかったデバイス
フォールバック: /dev/ttyACM0

通常は設定不要です。複数のCDCデバイスがあり、特定のデバイスを指定したい場合は以下のようにします：

FLIPPER_PORT=/dev/ttyACM1 uv run flipper-mcp-bridge

または、.mcp.json サーバーエントリに env を追加してください。

Claude Codeへの登録

リポジトリのルートに .mcp.json が含まれています。このディレクトリでセッションを開始すると、Claude Codeが自動的に読み込みます（初回起動時に信頼するかどうか尋ねられます）。明示的に登録したい場合は以下のようにします：

claude mcp add flipper -- uv run --directory "$(pwd)" flipper-mcp-bridge

既知の制限事項

キャプチャの遅延: learn_ir_button は、Flipperが実際にリッスンを開始するまでに数秒かかります。ツールを呼び出した直後ではなく、少し間を置いてからリモコンを押してください。
トランスポート: シリアル経由のCLIのみです。Protobuf RPCはまだ実装されていません。人間が操作するペースのIRには十分ですが、スループットが重要なフローについては今後見直される可能性があります。
フォアグラウンドアプリによるブロック: CLI以外のアプリ（ナイトスタンド時計のアイドル画面など）がFlipperを占有している場合、IR送信はブロックされます。ブリッジは競合時に一度 loader close を試みますが、デバイス上で手動で終了させる必要があるアプリもあります。
Raw IRキャプチャは未サポート: 未知のプロトコルの信号は、learn_ir_button を介した往復がまだできません。
IRのみ: Sub-GHz、NFC、RFID、GPIO、BadUSBなどは未実装です。