FPV Drone MCP Platform

A suite of three Model Context Protocol servers that give AI assistants (Claude, etc.) direct control over FPV drone hardware: radio transmitter configuration, flight controller tuning, and blackbox log analysis.

Claude ──MCP──┬── betaflight-mcp        ──USB/Serial──► Flight Controller
              ├── tango2-mcp-server     ──SD Card────► TBS Tango 2 Radio
              └── blackbox-mcp-server   ──Filesystem──► Blackbox Logs

Architecture

Total: 87 tools across 3 servers, ~8,600 lines of code.

---

betaflight-mcp

Communicates with Betaflight flight controllers over USB serial using the MSP protocol. Supports full configuration, telemetry, and fleet management.

Location: MCP/

Capabilities

• Connection: Auto-detect FC, connect/disconnect/reconnect with retry
• PID Tuning: Read/write PID settings, RC rates, filter config
• Modes & Switches: Configure AUX modes (ARM, ANGLE, HORIZON, etc.)
• OSD: Full OSD layout editing with presets (freestyle, long range, racing)
• VTX: Band, channel, power, pit mode control
• GPS: GPS status monitoring, GPS Rescue configuration
• Safety: Preflight checks, motor test (individual), emergency stop, beeper
• Fleet Management: Register multiple drones, backup all configs, compare settings
• Sensors: Live IMU data, attitude, battery status, RC channels, motor values
• CLI: Send raw Betaflight CLI commands, backup/restore via diff

Handler Modules

MCP/src/betaflight_mcp/
├── server.py          # MCP server + tool definitions + dispatch
├── msp.py             # MSP protocol implementation (v1)
└── handlers/
    ├── connection.py  # Serial port management
    ├── config.py      # PIDs, rates, filters, features, failsafe
    ├── sensors.py     # IMU, attitude, battery, RC, motors
    ├── safety.py      # Preflight, motor test, stop, calibration
    ├── fleet.py       # Multi-drone registry and bulk operations
    ├── osd.py         # OSD layout, elements, presets
    ├── vtx.py         # Video transmitter settings
    └── gps.py         # GPS status and rescue config

Setup

cd MCP
python -m venv venv
source venv/bin/activate
pip install -e .

MCP Config

{
  "mcpServers": {
    "betaflight": {
      "command": "MCP/venv/bin/python",
      "args": ["-m", "betaflight_mcp"]
    }
  }
}

Environment Variables

---

tango2-mcp-server

Reads and writes TBS Tango 2 radio model files directly at the binary level. The radio mounts as a USB mass storage device, and this server edits the .bin model files on its SD card.

Location: tango2-mcp-server/

Capabilities

• Radio Detection: Auto-detect Tango 2 mount point across macOS/Windows/Linux
• Model Management: List, read, create, compare, validate models
• Mix Editor: Set mixes, assign switches to AUX channels (SA-SF)
• Timer Config: Configure flight timers (countdown, throttle-triggered, etc.)
• Templates: Create models from presets (freestyle, long range, cinematic)
• Backup/Restore: Backup models with path traversal protection, restore from backup
• Backup Rotation: Auto-cleanup keeping last N backups per model
• Raw Debug: Hex dump any section of the binary file

Binary Format (otx5)

The parser handles the FreedomTX/OpenTX 2.3 binary format:

Offset  Size  Field
0x00    4     Fourcc "otx5"
0x04    10    Model name (ASCII)
0x0E    1     Model ID (5 bits)
0x0F    48    3 timers x 16 bytes (bitpacked: mode, start, countdown, persistent)
0x43    1280  64 mixes x 20 bytes (weight, destCh, srcRaw, offset, switch, curves, name)

MIXSRC Numbering: I1-I32 (1-32), LUA (33-74), MAX (75), Sticks: Rud=79/Ele=80/Thr=81/Ail=82, Pots: S1=83/S2=84, Switches: SA=89…SF=94, Channels: Ch1=95+

Setup

cd tango2-mcp-server
npm install
npm run build

MCP Config

{
  "mcpServers": {
    "tango2": {
      "command": "node",
      "args": ["tango2-mcp-server/dist/index.js"]
    }
  }
}

Environment Variables

---

blackbox-mcp-server

Parses Betaflight blackbox logs (.bbl, .bfl, .txt) and provides flight analysis with issue detection and tuning suggestions.

Location: blackbox-mcp-server/

Capabilities

• Log Discovery: List blackbox files in any directory with size and date info
• Flight Analysis: Parse logs and detect vibration issues, PID problems, desync events
• Time Series: Extract channel data (gyro, setpoint, motor, RC) with downsampling
• Channel Listing: Discover available data channels in a log file

Supported Formats

Setup

cd blackbox-mcp-server
npm install
npm run build

MCP Config

{
  "mcpServers": {
    "blackbox": {
      "command": "node",
      "args": ["blackbox-mcp-server/dist/index.js"]
    }
  }
}

Environment Variables

---

Unified Backup Structure

All three servers store backups under ~/.drone/:

~/.drone/
├── backups/
│   ├── tango2/        # Radio model .bin backups (timestamped)
│   ├── betaflight/    # FC CLI diff backups (.txt)
│   ├── blackbox/      # Analyzed log archive
│   └── mcp-config/    # Claude MCP config snapshots
└── fleet.json         # Multi-drone fleet registry

---

Standard Procedure

The recommended workflow when connecting a drone (per CLAUDE.md):

1. Backup configuration — backup_configuration (betaflight) + backup_model (tango2)
2. Check logs and blackbox — analyze_blackbox_log for recent flights
3. Give feedback — AI reviews PID tuning, filter settings, and flight data to suggest improvements

---

Testing

# Tango2 binary parser — 75 tests (vitest)
cd tango2-mcp-server && npm test

# Betaflight MSP protocol — 18 tests (pytest)
cd MCP && source venv/bin/activate && python -m pytest tests/ -v

Test coverage:

• FTXModelFile: Constructor validation, name get/set, timer roundtrips, mix read/write, srcRaw mapping, dumpRaw bounds checking, save persistence
• MSP Protocol: Checksum calculation, message building, response parsing, error handling (timeout, bad header, wrong code, corrupt checksum)
• Integration: Full create → configure → backup → modify → restore → verify cycle

---

Security

• Path traversal protection on restore_model — resolved paths validated against backup directory
• ASCII input validation on all binary writes — prevents corrupted model files from non-printable characters
• Bounds checking on raw memory reads — offset + length validated against file size
• Protected backups — backup failure throws before any modification to the original file

---

Hardware

Tested with:

• Radios: TBS Tango 2 (FreedomTX firmware)
• Flight Controllers: iFlight Blitz F722, BetaFPV F722
• Drones: iFlight Chimera 7 Pro V2 (long range), iFlight Nazgul Evoque F6 (freestyle)
• Protocol: TBS Crossfire (CRSF)
• Platform: macOS ARM (Apple Silicon)

---

License

MIT