flipper-mcp

एक Rust MCP (Model Context Protocol) सर्वर जो सीधे Flipper Zero के WiFi Dev Board v1 (ESP32-S2) पर चलता है, जिससे 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 एक HTTP सर्वर चलाता है जो MCP प्रोटोकॉल को लागू करता है। यह MCP टूल कॉल्स को 115200 baud पर 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 बाइनरी, कई Flippers का समर्थन करता है

आवश्यक हार्डवेयर

• Flipper Zero (CLI समर्थन वाला कोई भी फर्मवेयर संस्करण)
• WiFi Dev Board v1 (ESP32-S2-WROVER मॉड्यूल)

मैं किस डिवाइस से कनेक्ट करूँ?

चरण	कनेक्ट करें	नोट्स
फर्मवेयर फ्लैशिंग	WiFi Dev Board USB-C	बोर्ड का अपना USB पोर्ट है, Flipper से अलग
सीरियल मॉनिटरिंग	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

या सीधे Flipper से कॉन्फ़िगर करें साथी FAP का उपयोग करके (चरण 5 देखें): Apps → Tools → Flipper MCP → Configure WiFi

कॉन्फ़िग फ़ाइल के बिना पहले बूट पर, ESP32 प्रतीक्षा करता है और स्टेटस फ़ाइल में status=needs_config लिखता है। Flipper FAP इसे 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

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 + पासवर्ड दर्ज करने के लिए ऑन-स्क्रीन कीबोर्ड; SD कार्ड में config.txt लिखता है
View Logs	ESP32 द्वारा हर 30 सेकंड में लिखा गया स्क्रॉल करने योग्य डायग्नोस्टिक लॉग
Tools List	ESP32 पर वर्तमान में पंजीकृत सभी MCP टूल्स की स्क्रॉल करने योग्य सूची
Refresh Modules	ESP32 पर FAP डिस्कवरी रीस्कैन + modules.toml रीलोड को ट्रिगर करता है

ऐप SD कार्ड फ़ाइलों के माध्यम से संचार करता है (GPIO हेडर के अलावा कोई अतिरिक्त वायरिंग नहीं)। Configure WiFi पहला-बूट विज़ार्ड है — किसी फ़ोन, ब्राउज़र, या PC स्क्रिप्ट की आवश्यकता नहीं।

6. (वैकल्पिक) रिले के माध्यम से रिमोट एक्सेस