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

REMOVE PROPS before testing motors
Never arm indoors with props attached
Test failsafe before flying
Verify settings after making changes
Backup config before major changes

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
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