FPV_MCP - Betaflight MCP Server

An MCP (Model Context Protocol) server that allows Claude AI to interact with Betaflight flight controllers for FPV drone configuration, tuning, and management.

Overview

This MCP server enables natural language interaction with your FPV drone through Claude. Simply connect your drone via USB and ask Claude to read settings, adjust PIDs, manage blackbox logs, configure modes, and much more.

Tested with:

• Betaflight 4.5.0
• iFlight Blitz F722 (STM32F7)
• Works with any Betaflight-compatible flight controller

Features

Connection Management

• Auto-detect serial ports
• Connect/disconnect flight controllers
• Handle connection state properly

Read Configuration

• Flight controller info (board, firmware, target)
• PID settings and rates
• Filter configuration
• Battery settings
• Motor configuration
• VTX settings
• OSD configuration
• Blackbox settings
• Feature flags

Write Configuration

• Modify PIDs with validation (safe ranges 0-200)
• Change rates and expo
• Configure aux modes and switches
• Adjust VTX settings (band, channel, power, pit mode)
• Set failsafe configuration
• Toggle features on/off

Sensor Data (Real-time)

• Attitude (roll, pitch, yaw angles)
• IMU data (gyro, accelerometer, magnetometer)
• Battery status (voltage, current, mAh)
• Motor output values
• RC channel values

Safety Features

• PID values validated before applying
• Motor testing requires confirmation
• Calibration checks arming state
• Dangerous CLI commands blocked
• Motor values clamped to safe PWM range
• Changes require explicit save

Blackbox Management

• Check blackbox storage status
• Enter mass storage mode for log download
• Erase blackbox logs
• Parse blackbox headers for flight info

Installation

Prerequisites

• Python 3.10 or higher
• A Betaflight flight controller connected via USB
• Claude Desktop or Claude Code

Install from source

git clone https://github.com/jir13/MCP.git
cd MCP
pip install -e .

Or with uv (recommended):

git clone https://github.com/jir13/MCP.git
cd MCP
uv pip install -e .

Using Virtual Environment

cd ~/FPV_MCP
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Configuration

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "betaflight": {
      "command": "/path/to/FPV_MCP/venv/bin/python",
      "args": ["-m", "betaflight_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/FPV_MCP/src"
      }
    }
  }
}

Claude Code

claude mcp add betaflight -- python -m betaflight_mcp.server

Or with a specific path:

claude mcp add betaflight --scope user -- uv run --directory ~/FPV_MCP betaflight-mcp

Available Tools (45 total)

Connection (3 tools)

Tool	Description
list_serial_ports	List available serial ports
connect_flight_controller	Connect to a Betaflight FC
disconnect_flight_controller	Disconnect from FC

Flight Controller Info (2 tools)

Tool	Description
get_flight_controller_info	Get firmware and board info
get_flight_controller_status	Get status, sensors, arming state

PID & Rates (3 tools)

Tool	Description
get_pid_settings	Read current PID values
set_pid_settings	Modify PID values (with validation)
get_rc_tuning	Get rates and expo settings

Modes & Aux Channels (4 tools)

Tool	Description
get_available_modes	List all flight modes (ARM, ANGLE, HORIZON, etc.)
get_aux_modes	Get aux channel to mode mappings
set_aux_mode	Map mode to aux channel range
clear_aux_mode	Remove a mode mapping

Profiles (4 tools)

Tool	Description
get_current_profile	Get active PID/rate profile
set_pid_profile	Switch PID profile (1-3)
set_rate_profile	Switch rate profile (1-6)
copy_pid_profile	Copy profile to another

Failsafe & Safety (3 tools)

Tool	Description
get_failsafe_config	Get failsafe settings
set_failsafe_config	Configure failsafe behavior
get_arming_disable_flags	Why can't I arm?
preflight_check	Comprehensive pre-flight checks

VTX Control (5 tools)

Tool	Description
get_vtx_config	Get VTX settings
set_vtx_channel	Change VTX channel (1-8)
set_vtx_band	Change VTX band (A, B, E, F, R)
set_vtx_power	Change VTX power level
set_vtx_pit_mode	Toggle pit mode on/off

Sensor Data (5 tools)

Tool	Description
get_attitude	Current roll/pitch/yaw angles
get_imu_data	Raw accelerometer/gyro/magnetometer
get_battery_status	Voltage, current, mAh consumed
get_motor_values	Current motor output values
get_rc_channels	RC receiver channel values

Configuration (8 tools)

Tool	Description
get_filter_config	Gyro and D-term filter settings
get_battery_config	Battery voltage/capacity settings
get_motor_config	Motor protocol, throttle limits
get_osd_config	On-screen display settings
get_blackbox_config	Data logging configuration
get_dataflash_summary	Onboard flash memory status
get_features	Enabled/disabled features
set_feature	Toggle features on/off

Motor Testing (2 tools)

Tool	Description
test_motor	Spin individual motor (REMOVE PROPS!)
stop_motors	Stop all motors immediately

Calibration (2 tools)

Tool	Description
calibrate_accelerometer	Level calibration
calibrate_magnetometer	Compass calibration

Utilities (6 tools)

Tool	Description
beep	Make the FC beep
reboot_flight_controller	Reboot the FC
erase_blackbox_logs	Clear onboard flash
set_craft_name	Set craft name
save_settings	Save changes to EEPROM
backup_configuration	Export config as CLI commands
send_cli_command	Send raw CLI commands

Usage Examples

Connection & Info

"List the available serial ports and connect to my drone"
"What's the firmware version on my flight controller?"
"Is my drone armed? What sensors are detected?"

Modes & Switches

"Show me my current aux mode mappings"
"Set ARM on AUX1 when the switch is high (1800-2100)"
"Map ANGLE mode to AUX2 middle position"

Tuning

"Show me the current PID settings"
"Increase the roll P gain by 10"
"What are my current filter settings?"

VTX Control

"Show me my VTX settings"
"Set VTX to band R channel 8"
"Enable pit mode"

Safety

"Run a preflight check"
"Why can't my drone arm?"
"What's my failsafe configuration?"

Blackbox

"Check blackbox storage"
"How much blackbox space is left?"
"Erase the blackbox logs"

Motor Testing (REMOVE PROPS FIRST!)

"Test motor 1 at 5% throttle"
"Stop all motors"

Backup & Restore

"Create a backup of my configuration"
"Run 'diff' to see changed settings"

MSP Protocol

This server implements MSPv1 (MultiWii Serial Protocol) for communication with Betaflight. The protocol uses:

• Baud rate: 115200
• Message format: $M< + length + command + data + checksum

Key MSP Codes Used

Code	Name	Description
100	MSP_IDENT	Legacy identification
101	MSP_STATUS	FC status
102	MSP_RAW_IMU	Raw sensor data
108	MSP_ATTITUDE	Orientation
110	MSP_ANALOG	Battery/RSSI
112	MSP_PID	PID values
202	MSP_SET_PID	Write PIDs
34	MSP_MODE_RANGES	Aux mode mappings
75	MSP_FAILSAFE_CONFIG	Failsafe settings
88	MSP_VTX_CONFIG	VTX configuration

Project Structure

FPV_MCP/
├── src/
│   └── betaflight_mcp/
│       ├── __init__.py      # Package exports
│       ├── msp.py           # MSP protocol implementation
│       └── server.py        # MCP server & tools
├── pyproject.toml           # Package configuration
├── setup.py                 # Pip compatibility
└── README.md                # This file

Troubleshooting

Serial port not found

• Ensure FC is connected via USB
• Close Betaflight Configurator (it locks the port)
• On Linux: sudo usermod -a -G dialout $USER

Connection timeout

• Check FC is powered and not in DFU mode
• Try unplugging and reconnecting USB
• Verify baud rate is 115200

Permission denied

• macOS: Grant terminal access to serial port
• Linux: Check udev rules or add user to dialout group

Port busy error

• Another application is using the serial port
• Close Betaflight Configurator or other serial monitors

Safety Warnings

1. REMOVE PROPS before testing motors
2. Never arm indoors with props attached
3. Test failsafe before flying
4. Verify settings after making changes
5. Backup config before major changes

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT

Acknowledgments

• Betaflight - Flight controller firmware
• MCP Protocol - Model Context Protocol by Anthropic
• MultiWii Serial Protocol documentation

---

Built for the FPV community