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)

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

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

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

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

• Xtensa toolchain — 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. Сборка и прошивка 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 и предоставляет:

Приложение взаимодействует через файлы на SD-карте (без дополнительной проводки помимо GPIO-разъёма). Configure WiFi — это мастер первой загрузки — без телефона, браузера или скриптов на ПК.

6. (Опционально) Удалённый доступ через relay

Самостоятельный хостинг (запустите бинарник где угодно):

./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 или установив FAP-приложения на SD-карту. См. OPERATIONS.md для готовых к копированию команд curl для каждого инструмента.

Бесплатная альтернатива: Open WebUI + Ollama

Вам не нужна подписка Claude для использования flipper-mcp. Open WebUI — это бесплатный, самостоятельно размещаемый интерфейс в стиле ChatGPT, который изначально поддерживает MCP Streamable HTTP (v0.6.31+). В сочетании с 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. Подключите MCP-сервер Flipper

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)
   • Через relay: https://relay.example.com/mcp
   • Из Docker: используйте http://host.docker.internal:8080/mcp, если Flipper находится в сети хоста Docker
5. Установите Authentication в None (у flipper-mcp нет аутентификации)
6. Save

Совет: В разделе Workspace → Models → (ваша модель) → Advanced Parameters установите Function Calling в Default для меньших моделей. Переключайтесь на Native только для моделей с сильной встроенной поддержкой инструментов (Llama 3.1 8B+, Qwen 2.5, Mistral).

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