flipper-mcp-bridge
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ツール
ツール | 用途 |
| Flipperの |
| SDカード上のディレクトリ内の |
| 保存された |
| 保存された |
| MSBファーストの整数16進数(例: |
| ファームウェアで利用可能な内蔵ユニバーサルIRリモコン(ac, tv, fansなど)をリスト表示する |
| 内蔵ユニバーサルリモコンの信号名をリスト表示する |
| 内蔵ユニバーサルリモコンから指定した信号を送信する |
| FlipperをRXモードにし、次のリモコン操作をキャプチャして |
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 / rebootattach 後、FlipperはWSL上で /dev/ttyACM0 として認識されます。
2. WSLでシリアルアクセス権限を付与する
sudo usermod -aG dialout $USERその後、グループを有効にするためにWSLを再起動します:
wsl.exe --shutdownシェルを再起動します。groups に dialout が含まれているはずです。
3. 依存関係のインストール
リポジトリのルートから:
uv sync4. 動作確認
uv run python scripts/smoketest_readonly.pyデバイス情報、/ext/infrared/ 以下のファイルリスト、および各 .ir ファイルの解析内容が表示されるはずです。
実行方法
MCP stdio(Claude Code、Cursorなど用):
uv run flipper-mcp-bridgeHTTP REST API(Home Assistant、curl、スクリプト用):
uv run flipper-mcp-bridge --http --port 8765エンドポイント:
メソッド | パス | ボディ / クエリ |
|
| — |
|
| — |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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などは未実装です。
Available Tools
10 toolsdelete_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Related MCP Servers
- FlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to control TVs on a local network through natural language commands. It currently supports Roku devices, allowing users to launch apps, manage playback, and navigate menus.51-
- AlicenseNot gradedqualityDmaintenanceModular 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.36MIT
- FlicenseBqualityDmaintenanceMCP server for controlling MicroPython devices (ESP32, RP2040, etc.) via USB Serial or WebREPL, enabling code execution, file operations, and device management from MCP clients.299-
- AlicenseAqualityBmaintenanceAn 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.2433 PyPI1MIT