flipper-mcp

Rust-сервер MCP (Model Context Protocol), работающий непосредственно на WiFi Dev Board v1 (ESP32-S2) устройства Flipper Zero, позволяющий AI-агентам управлять Flipper Zero по сети.

Что это?

Этот проект размещает MCP-сервер на самом Flipper. Любой MCP-совместимый AI-клиент (Claude Desktop, Claude Code и т. д.) может подключиться и использовать возможности Flipper как инструменты — SubGHz, NFC, RFID, IR, GPIO, BadUSB, iButton, файловое хранилище и многое другое.

В отличие от других проектов, требующих подключённого по USB хост-компьютера, flipper-mcp работает на модуле ESP32-S2 WiFi, прикреплённом к Flipper. 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 запускает HTTP-сервер, реализующий протокол MCP. Он преобразует вызовы инструментов MCP в команды CLI Flipper Zero через UART на скорости 115200 бод. Сопутствующий relay-сервер обеспечивает удалённый доступ из любой сети.

Возможности

• ~30 встроенных инструментов, охватывающих все стандартные приложения Flipper Zero
• Динамическое обнаружение модулей — автоопределение FAP-приложений с SD-карты + инструменты на основе конфигурации TOML
• Настройка через Flipper — настройка WiFi из FAP на Flipper (без телефона, браузера или скриптов на ПК)
• Двойной транспорт MCP — Streamable HTTP (современный) + Legacy SSE (обратная совместимость)
• Локальное обнаружение — объявление mDNS как flipper-mcp.local
• Удалённый доступ — обратный туннель WebSocket через relay-сервер (без проброса портов)
• Без аутентификации — разработан для сценариев пентестинга и исследований в области безопасности
• Сопутствующий relay-сервер — небольшой Rust-бинарник для доступа между сетями, поддерживает несколько Flipper

Необходимое оборудование

• Flipper Zero (любая версия прошивки с поддержкой CLI)
• WiFi Dev Board v1 (модуль ESP32-S2-WROVER)

К какому устройству подключаться?

Этап	Подключение к	Примечания
Прошивка firmware	WiFi Dev Board USB-C	У платы собственный USB-порт, отдельный от Flipper
Мониторинг последовательного порта	WiFi Dev Board USB-C	То же USB-подключение, что и для прошивки
Конфигурационные файлы на SD-карте	Flipper Zero SD card	Вставьте SD в Flipper или извлеките и подключите к ПК
Команды управления сервером	Flipper Zero SD card	Создайте файл server.cmd в apps_data/flipper_mcp/
UART-связь	Автоматически	WiFi Dev Board и Flipper соединяются через GPIO-разъём
HTTP-запросы MCP	WiFi Dev Board IP:8080	Подключение через вашу WiFi-сеть

Предварительные требования

• Rust — установите через rustup:

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

• Xtensa toolchain — 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. Сборка и прошивка firmware

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

Создайте config.txt на SD-карте Flipper по пути SD:/apps_data/flipper_mcp/config.txt:

wifi_ssid=YourNetworkName
wifi_password=YourPassword
device_name=flipper-mcp

Или настройте прямо с Flipper с помощью сопутствующего FAP (см. Шаг 5): Apps → Tools → Flipper MCP → Configure WiFi

При первой загрузке без конфигурационного файла ESP32 ожидает и записывает status=needs_config в файл статуса. FAP на Flipper отобразит это на экране Status.

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

Тестирование инструментов MCP напрямую через curl

Получите IP-адрес Flipper из меню Flipper MCP → Status, затем протестируйте:

Широковещательная передача 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 (отправка кодов инфракрасного пульта):

# 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 МГц):

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 на фактический IP-адрес вашего Flipper.

Затем добавьте в конфигурацию Claude Desktop (claude_desktop_config.json):

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

5. Управление WiFi-платой с Flipper

Установите сопутствующее приложение Flipper MCP из flipper-app/ на 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	Управляет жизненным циклом HTTP-сервера MCP
Reboot Board	Перезагружает WiFi Dev Board ESP32
Configure WiFi	Экранная клавиатура для ввода SSID + пароля; записывает config.txt на SD-карту
View Logs	Прокручиваемый диагностический журнал, записываемый ESP32 каждые 30 с
Tools List	Прокручиваемый список всех инструментов MCP, зарегистрированных в данный момент на ESP32
Refresh Modules	Запускает повторное сканирование обнаружения FAP + перезагрузку modules.toml на ESP32