Skip to main content
Glama
flipper-mcp-bridge

flipper-mcp-bridge

by dudebot

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 ファイルに追記する

Related MCP server: Flipper Zero MCP Server

セットアップ(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つの簡単な構成がそのまま利用可能です:

  1. ブリッジをHAと同じホストで実行する(Flipperを接続したPi/NUC/サーバー)。HAは http://127.0.0.1:8765 にアクセスします。これが最も簡単です。

  2. 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側で管理されます)。

ポートの選択

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

  1. 明示的な port= 引数(ライブラリ使用時のみ)

  2. FLIPPER_PORT 環境変数

  3. 自動検出: USBメーカーが "Flipper Devices Inc."(またはVID:PID 0483:5740)である最初に見つかったデバイス

  4. フォールバック: /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などは未実装です。

Available Tools

10 tools
delete_ir_buttonB

Remove a named button from an .ir file (reads, filters, rewrites).

Inputs: file (required), button (required).

device_infoA

Return the Flipper's device_info dict (firmware, hardware, radio, etc.).

Inputs: no named parameters. Returns: object

learn_ir_buttonA

Put Flipper in IR RX, wait for a single remote press (up to timeout_seconds), then append the captured signal as a named button to the given .ir file. Creates the file if it doesn't exist. The user must press a physical remote at the Flipper during the capture window.

Inputs: file (required), button (required), timeout_seconds.

list_ir_buttonsB

Parse a saved .ir file on the Flipper and return its buttons.

Inputs: file (required). Returns: result

list_ir_filesA

List .ir files under a directory on the Flipper's SD card (non-recursive).

Inputs: directory. Returns: result

list_universal_remotesA

List the built-in universal IR remote names on this firmware (ac, tv, fans, ...).

Inputs: no named parameters. Returns: result

list_universal_signalsB

List the signal names available for a built-in universal remote (e.g. POWER, VOL+).

Inputs: remote (required). Returns: result

send_ir_buttonB

Transmit a named button from a saved .ir file on the Flipper. Raises on CLI error.

Inputs: file (required), button (required).

send_ir_signalA

Transmit an ad-hoc parsed IR signal. address and command are MSB-first integer hex as reported by ir rx (e.g. protocol='NECext', address='DF02', command='EE11'). Optional '0x' prefix is fine. Raises on CLI error.

Inputs: protocol (required), address (required), command (required).

send_universal_signalB

Transmit a named signal from a built-in universal remote (e.g. remote='ac', signal='OFF').

Inputs: remote (required), signal (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct action or resource: device_info for hardware info, list_* for browsing, learn_* for capturing, send_* for transmitting, and delete_* for removal. No two tools overlap in purpose.

    Naming Consistency4/5

    Most tools follow a verb_ir_noun or verb_universal_noun pattern (e.g., delete_ir_button, send_universal_signal). The one exception is device_info, which uses noun_noun, breaking the pattern slightly.

    Tool Count5/5

    With 10 tools, the server covers the core IR workflows (browse, learn, send, delete) without being overwhelming. The count feels well-scoped for the domain.

    Completeness3/5

    Basic IR operations are covered, but there are gaps: no tool to delete an entire .ir file, rename a file or button, or directly create an empty file. These missing operations may cause workflow dead ends.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Modular MCP server for interacting with a Flipper Zero from MCP-capable clients (including Claude Desktop). Supports system info, BadUSB scripts, and music playback over USB or WiFi.
      36
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that connects to Z-Wave JS UI's WebSocket to expose controller, node, and configuration information as tools for AI assistants to manage Z-Wave networks.
      24
      33 PyPI
      1
      MIT