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 मॉड्यूल)

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

पूर्वापेक्षाएँ

• 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

या सीधे 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 में दिखाई देता है और प्रदान करता है:

ऐप 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 एक मुफ़्त, स्व-होस्टेड ChatGPT-शैली इंटरफ़ेस है जो मूल रूप से MCP Streamable HTTP (v0.6.31+) का समर्थन करता है। पूरी तरह से स्थानीय, ऑफ़लाइन AI-संचालित Flipper नियंत्रण के लिए इसे Ollama के साथ जोड़ें।

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-संगत APIs के माध्यम से क्लाउड मॉडल्स) के साथ सबसे अच्छा काम करते हैं। छोटे मॉडल्स सिंगल-टूल कॉल्स को विश्वसनीय रूप से संभालते हैं।

प्रोजेक्ट संरचना

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