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モジュール）

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

前提条件

• Rust — rustup経由でインストール:
  root@kitploit:~

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

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

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

• フラッシュツール & リンカープロキシ:
  root@kitploit:~

  cargo install espflash
  cargo install ldproxy
  

• システムパッケージ（Debian/Ubuntu/Kali）:
  root@kitploit:~

  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に表示され、以下を提供します:

アプリは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を参照してください。

利用可能なツール

カスタムツールはTOML設定ファイル経由、またはSDカードにFAPアプリをインストールすることで追加できます。すべてのツールのコピー&ペースト可能なcurlコマンドについてはOPERATIONS.mdを参照してください。

無料の代替手段: Open WebUI + Ollama

flipper-mcpを使うのにClaudeのサブスクリプションは必要ありません。Open WebUIは、MCP Streamable HTTP（v0.6.31+）をネイティブサポートする無料のセルフホスト型ChatGPT風インターフェースです。Ollamaと組み合わせることで、完全にローカルでオフラインのAI駆動Flipper制御が可能になります。

1. Ollamaをインストールし、ツール対応モデルをプルする

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model with tool-calling support
ollama pull llama3.1        # 8B — good balance of speed and capability
# or: ollama pull qwen2.5   # strong tool-calling, good at structured output
# or: ollama pull mistral    # lightweight, fast tool use

2. Open WebUIを起動する

# Docker (recommended) — connects to Ollama on localhost automatically
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e WEBUI_AUTH=False \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

# Or without Docker:
pip install open-webui
open-webui serve

ブラウザで**http://localhost:3000**を開きます。

3. Flipper MCPサーバーを接続する

1. Admin Settings（歯車アイコン）→ External Toolsに移動
2. + Add Serverをクリック
3. Typeを**MCP (Streamable HTTP)**に設定
4. サーバーURLを入力:
   • ローカル: http://flipper-mcp.local:8080/mcp（またはhttp://192.168.x.x:8080/mcp）
   • リレー経由: https://relay.example.com/mcp
   • Dockerから: FlipperがDockerホストのネットワーク上にある場合はhttp://host.docker.internal:8080/mcpを使用
5. AuthenticationをNoneに設定（flipper-mcpには認証がありません）
6. Save

ヒント: Workspace → Models → (your model) → Advanced Parametersで、小さいモデルの場合はFunction CallingをDefaultに設定します。組み込みのツールサポートが強力なモデル（Llama 3.1 8B+、Qwen 2.5、Mistral）のみNativeに切り替えてください。

4. プロンプト例

接続したら、Open WebUIチャットでこれらを試してください:

マルチステップのエージェントタスクは、より大きなモデル（Llama 3.1 70B、Qwen 2.5 72B、またはOpenAI互換API経由のクラウドモデル）で最もよく機能します。小さいモデルは単一ツール呼び出しを確実に処理します。

プロジェクト構成

flipper-mcp/
├── firmware/          # ESP32-S2 firmware (Rust, esp-idf-svc)
├── relay/             # Companion relay server (Rust, tokio/axum)
├── flipper-app/       # Flipper Zero FAP — in-device management UI (C, ufbt)
├── infra/             # OpenTofu IaC — cloud relay deployment (AWS + GCP)
├── config/            # Example module configurations
├── scripts/           # Build, flash, and setup helper scripts
└── docs/              # Architecture, setup, API, troubleshooting

ドキュメント

• SETUP.md — ゼロからの完全セットアップ
• ARCHITECTURE.md — システム設計の詳細
• API.md — 完全なMCPツールリファレンス
• OPERATIONS.md — すべてのツールのcurlコマンド付き運用ガイド
• MODULE_DEVELOPMENT.md — カスタムモジュールの作成
• RELAY.md — リモートアクセスのセットアップ
• HARDWARE.md — 配線とハードウェアの詳細
• TROUBLESHOOTING.md — 一般的な問題と修正
• DESIGN.md — 技術設計とシステムアーキテクチャ

AIエージェント向け

完全なプロジェクトコンテキスト、技術仕様、システムアーキテクチャ、およびこのプロジェクトの開発を継続するために必要なすべてについてはAGENTS.mdを参照してください。

ライセンス

MIT