flipper-mcp

Flipper ZeroのWiFi Dev Board v1（ESP32-S2）上で直接動作するRust製MCP（Model Context Protocol）サーバー。AIエージェントがネットワーク経由でFlipper Zeroを制御できるようにします。

これは何？

このプロジェクトは、MCPサーバーをFlipper本体上に配置します。MCP互換のAIクライアント（Claude Desktop、Claude Codeなど）が接続し、Flipperの機能をツールとして利用できます — SubGHz、NFC、RFID、IR、GPIO、BadUSB、iButton、ファイルストレージなど。

USB接続されたホストコンピュータを必要とする他のプロジェクトとは異なり、flipper-mcpはFlipperに接続されたESP32-S2 WiFiモジュール上で動作します。Flipperはスタンドアロンでネットワークアクセス可能なツールになります。

アーキテクチャ

LOCAL (same network):
  MCP Client ──HTTP──► flipper-mcp.local:8080 (ESP32-S2) ──UART──► Flipper Zero

REMOTE (cross-network):
  MCP Client ──HTTP──► Relay Server ◄──WebSocket── ESP32-S2 ──UART──► Flipper Zero

ESP32-S2はMCPプロトコルを実装したHTTPサーバーを実行します。MCPツール呼び出しを、115200ボーのUART経由でFlipper ZeroのCLIコマンドに変換します。コンパニオンリレーサーバーにより、任意のネットワークからのリモートアクセスが可能になります。

機能

約30の組み込みツール — すべてのデフォルトFlipper Zeroアプリケーションをカバー
動的モジュール検出 — SDカードからのFAPアプリ自動検出 + TOML設定駆動のツール
Flipperファーストのセットアップ — Flipper FAPからWiFiを設定（スマホ、ブラウザ、PCスクリプト不要）
デュアルMCPトランスポート — Streamable HTTP（モダン）+ Legacy SSE（後方互換）
ローカル検出 — flipper-mcp.localとしてmDNSアドバタイズ
リモートアクセス — リレーサーバー経由のリバースWebSocketトンネル（ポートフォワーディング不要）
認証なし — ペネトレーションテストおよびセキュリティ研究シナリオ向けに設計
コンパニオンリレーサーバー — クロスネットワークアクセス用の小さなRustバイナリ、複数のFlipperをサポート

必要なハードウェア

Flipper Zero（CLIサポートのある任意のファームウェアバージョン）
WiFi Dev Board v1（ESP32-S2-WROVERモジュール）

どのデバイスに接続すればよいですか？

段階	接続先	備考
ファームウェアの書き込み	WiFi Dev Board USB-C	ボードにはFlipperとは別の独自のUSBポートがあります
シリアルモニタリング	WiFi Dev Board USB-C	書き込みと同じUSB接続
SDカード設定ファイル	Flipper Zero SDカード	SDをFlipperに挿入するか、取り外してPCにマウント
サーバー制御コマンド	Flipper Zero SDカード	`apps_data/flipper_mcp/`に`server.cmd`ファイルを作成
UART通信	自動	WiFi Dev BoardとFlipperはGPIOヘッダー経由で接続
MCP HTTPリクエスト	WiFi Dev Board IP:8080	WiFiネットワーク経由で接続

前提条件

Rust — rustup経由でインストール:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Xtensaツールチェーン — ESP32-S2にはカスタムRustツールチェーンが必要:

cargo install espup
espup install
source ~/export-esp.sh  # Run this in every new terminal

フラッシュツール & リンカープロキシ:
```
cargo install espflash
cargo install ldproxy
```

システムパッケージ（Debian/Ubuntu/Kali）:

sudo apt install -y git curl gcc build-essential pkg-config libudev-dev libssl-dev python3 python3-venv cmake ninja-build

クイックスタート

完全なセットアップ手順はdocs/SETUP.mdにあります

1. ファームウェアのビルド & 書き込み

source ~/export-esp.sh
cd firmware
cargo build --release --target xtensa-esp32s2-espidf
espflash flash --monitor target/xtensa-esp32s2-espidf/release/flipper-mcp

3. WiFiの設定

Flipper SDカードのSD:/apps_data/flipper_mcp/config.txtにconfig.txtを作成します:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

またはコンパニオンFAPを使ってFlipperから直接設定（ステップ5参照）: Apps → Tools → Flipper MCP → Configure WiFi

設定ファイルなしで初回起動すると、ESP32は待機し、ステータスファイルにstatus=needs_configを書き込みます。Flipper FAPはこれをステータス画面に表示します。

4. サーバーが動作していることを確認する

AIクライアントを設定する前に、curlでサーバーに到達可能であることを確認します:

# Quick health check
curl http://flipper-mcp.local:8080/health

# Full verification — initialize + list all available tools
./scripts/test-connection.sh

# If mDNS isn't resolving on your OS, pass the IP directly:
./scripts/test-connection.sh 192.168.x.xxx

curlでMCPツールを直接テストする

Flipper MCP → StatusメニューからFlipperのIPを取得し、テストします:

BLEビーコン送信（スプーフィングされたBLEアドバタイズを送信）:

curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_beacon","arguments":{"data":"020106"}}}'

BLE HIDキーボード（ワイヤレスキーボードをエミュレートして入力）:

# Start HID emulation
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ble_hid_start","arguments":{}}}'

# Type a message
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ble_hid_type","arguments":{"text":"Hello from Flipper!"}}}'

# Stop HID emulation
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ble_hid_stop","arguments":{}}}'

IR送信（IRリモコンコードを送信）:

# NEC protocol IR code (generic TV power button)
curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ir_tx","arguments":{"protocol":"NEC","address":"00","command":"01","repeat":0}}}'

SubGHz受信（433.92 MHzの無線信号を傍受）:

curl -X POST http://192.168.0.58:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"subghz_rx","arguments":{"frequency":433920000,"duration":5000}}}'

192.168.0.58をFlipperの実際のIPアドレスに置き換えてください。

次に、Claude Desktopの設定（claude_desktop_config.json）に追加します:

{
  "mcpServers": {
    "flipper": {
      "url": "http://flipper-mcp.local:8080/mcp"
    }
  }
}

5. FlipperからWiFiボードを管理する

flipper-app/からコンパニオンFlipper MCPアプリをFlipper Zeroにインストールします。ufbtでビルドし、.fapをSD:/apps/Tools/にコピーします:

cd flipper-app && ufbt   # produces flipper_mcp.fap
# Copy flipper_mcp.fap to your Flipper SD card under apps/Tools/

アプリはApps → Tools → Flipper MCPに表示され、以下を提供します:

画面	機能
Status	ESP32に最新のステータス更新を要求し、IP、SSID、サーバー状態、バージョンを表示
Start / Stop / Restart	MCP HTTPサーバーのライフサイクルを制御
Reboot Board	ESP32 WiFi Dev Boardを再起動
Configure WiFi	SSID + パスワードを入力するオンスクリーンキーボード。`config.txt`をSDカードに書き込み
View Logs	ESP32が30秒ごとに書き込むスクロール可能な診断ログ
Tools List	ESP32に現在登録されているすべてのMCPツールのスクロール可能なリスト
Refresh Modules	ESP32でFAP検出の再スキャン + `modules.toml`の再読み込みをトリガー

アプリはSDカードファイル経由で通信します（GPIOヘッダー以外の追加配線は不要）。Configure WiFiは初回起動ウィザードです — スマホ、ブラウザ、PCスクリプトは不要です。

6. （オプション）リレー経由のリモートアクセス

セルフホスト（バイナリをどこでも実行）:

./scripts/build-relay.sh
./target/release/flipper-mcp-relay --listen 0.0.0.0:9090
# Then add relay_url to config.txt on the Flipper SD card:
# relay_url=ws://your-server:9090/tunnel

クラウドデプロイ（AWSまたはGCP、TLS + DNS付き）:

# Bootstrap state storage, then deploy
./infra/bootstrap/aws.sh   # or ./infra/bootstrap/gcp.sh
cd infra/aws && cp terraform.tfvars.example terraform.tfvars
tofu init && tofu apply
# Outputs the relay URL and a ready-to-paste wifi-config.sh command

完全な手順はRELAY.mdを参照してください。

利用可能なツール

カテゴリ	ツール	説明
SubGHz	`subghz_tx`, `subghz_rx`, `subghz_decode_raw`, `subghz_chat`, `subghz_tx_from_file`	無線周波数操作
NFC	`nfc_detect`, `nfc_read`, `nfc_emulate`, `nfc_field`	NFCタグ操作
RFID	`rfid_read`, `rfid_emulate`, `rfid_write`	低周波RFID
Infrared	`ir_tx`, `ir_rx`	IRリモートコントロール
GPIO	`gpio_read`, `gpio_write`, `gpio_set_mode`	ピンI/O制御
BadUSB	`badusb_run`, `badusb_list`	USB HID攻撃
iButton	`ibutton_read`, `ibutton_emulate`	1-Wireキーフォブ
Storage	`storage_list`, `storage_read`, `storage_write`, `storage_remove`, `storage_stat`	SDカードファイル管理
System	`system_device_info`, `system_power_info`, `system_power_reboot`, `system_ps`, `system_free`, `system_uptime`	デバイス管理
BLE	`ble_info`, `ble_beacon`, `ble_beacon_stop`, `ble_hid_start`, `ble_hid_type`, `ble_hid_press`, `ble_hid_mouse`, `ble_hid_stop`	Bluetooth Low Energy（ビーコン送信 + HIDエミュレーション）
Apps	`app_launch_{name}`（SDカードから自動検出）	アプリケーション管理

人気

flipper-mcp

flipper-mcp

これは何？

アーキテクチャ

機能

必要なハードウェア

前提条件

クイックスタート

1. ファームウェアのビルド & 書き込み

3. WiFiの設定

4. サーバーが動作していることを確認する

curlでMCPツールを直接テストする

5. FlipperからWiFiボードを管理する

6. （オプション）リレー経由のリモートアクセス

利用可能なツール