FPV_MCP - Betaflight

You set up an MCP server to let Claude interact with your Betaflight flight controller for FPV drone configuration, tuning, and management. Connect your FC via USB, then read and adjust PIDs, rates, filters, modes, VTX settings, and more from natural language prompts. The server also handles safety checks, real-time sensor data, and blackbox management to streamline your flight control workflow.

How to use

Use an MCP client to connect to the Betaflight MCP server and issue high-level commands like reading current configuration, changing PIDs, updating rates, mapping aux modes, configuring VTX, arming/disarming with safety checks, and accessing live sensor data. You can request actions such as reading PID values, applying safety-validated changes, starting a motor test with explicit confirmation, and downloading blackbox logs. All changes are persisted when you explicitly save.

How to install

Prerequisites you need before installing: Python 3.10 or higher, a Betaflight flight controller connected via USB, and Claude Desktop or Claude Code.

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

# Recommended alternative using uvx for development
git clone https://github.com/jir13/MCP.git
cd MCP
uv pip install -e .

To run in a virtual environment, use the steps below, then install the package in editable mode.

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

Configuration examples

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

Claude integration notes

# Claude Desktop integration example (config.json path shown for macOS/Windows)
# macOS
~/Library/Application Support/Claude/claude_desktop_config.json
# Windows
%APPDATA%\Claude\claude_desktop_config.json

# Claude Code integration example
claude mcp add betaflight -- python -m betaflight_mcp.server

(Optional path example)

## Additional configuration and notes

This server provides a comprehensive set of tools to interact with Betaflight firmware via MCP. It supports both reading and writing configuration, real-time sensor data, safety checks, and blackbox management. Ensure you save changes explicitly to persist them.

## Troubleshooting

If the serial port cannot be found, ensure the FC is connected via USB and close any other software (like Betaflight Configurator) that might lock the port. On Linux, add your user to the dialout group to access serial devices.

## Safety and best practices

Follow these safety guidelines: remove propellers before testing motors, never arm indoors with props attached, run a preflight check, verify settings after changes, and back up the configuration before major modifications.

## MSP protocol and data flow

This server uses an MSPv1-based protocol over a serial connection to communicate with Betaflight. Typical interaction includes requesting attitude, reading PID values, and applying write commands with validation.

## Project structure and repository layout

The MCP server exposes a Python package with modules for MSP handling and the server logic. You will find the CLI and server entry points under the betaflight\_mcp package.

## Quick start commands and common use cases

To read current PID settings, request the current attitude, or check the battery status, issue natural language prompts to Claude after connecting the FC. Use safety-confirmed commands for motor tests and saves to store changes.

## Available tools

### list\_serial\_ports

List available serial ports for connecting to the flight controller.

### connect\_flight\_controller

Establish a connection to the Betaflight flight controller over USB.

### disconnect\_flight\_controller

Disconnect from the currently connected flight controller.

### get\_flight\_controller\_info

Read firmware, board, and target information from the FC.

### get\_flight\_controller\_status

Return current FC status including arming state and sensor availability.

### get\_pid\_settings

Read current PID values and controller gains.

### set\_pid\_settings

Modify PID values with validation and constraints.

### get\_rc\_tuning

Retrieve RC rates and expo settings.

### get\_available\_modes

List all supported flight modes and their capabilities.

### get\_aux\_modes

Query the mappings from aux channels to modes.

### set\_aux\_mode

Assign a mode to a specific aux channel range.

### clear\_aux\_mode

Remove a mode mapping from an aux channel.

### get\_current\_profile

Get the active PID/rate profile.

### set\_pid\_profile

Switch the PID profile (1-3).

### set\_rate\_profile

Switch the rate profile (1-6).

### copy\_pid\_profile

Copy a PID profile to another slot.

### get\_failsafe\_config

Retrieve current failsafe settings.

### set\_failsafe\_config

Configure failsafe behavior for loss of signal.

### get\_arming\_disable\_flags

Explain why arming is blocked if applicable.

### preflight\_check

Run a comprehensive pre-flight system check.

### get\_vtx\_config

Fetch current VTX configuration.

### set\_vtx\_channel

Set VTX transmission channel.

### set\_vtx\_band

Set VTX band (A, B, E, F, R).

### set\_vtx\_power

Adjust VTX power level.

### set\_vtx\_pit\_mode

Toggle VTX pit mode.

### get\_attitude

Get current roll/pitch/yaw attitude.

### get\_imu\_data

Retrieve raw IMU data from gyro/accelerometer/magnetometer.

### get\_battery\_status

Read voltage, current, and mAh consumed.

### get\_motor\_values

Get current motor output values.

### get\_rc\_channels

Read RC receiver channel values.

### get\_filter\_config

Read gyro and D-term filter settings.

### get\_battery\_config

Read battery voltage and capacity settings.

### get\_motor\_config

Read motor protocol and throttle limits.

### get\_osd\_config

Read on-screen display configuration.

### get\_blackbox\_config

Read data logging configuration.

### get\_dataflash\_summary

Get onboard flash memory status.

### get\_features

List enabled/disabled features.

### set\_feature

Toggle features on or off.

### test\_motor

Spin a single motor for testing (remove props first).

### stop\_motors

Stop all motors immediately.

### calibrate\_accelerometer

Calibrate the accelerometer for level reference.

### calibrate\_magnetometer

Calibrate the compass (magnetometer).

### beep

Trigger a beep from the flight controller.

### reboot\_flight\_controller

Reboot the FC safely.

### erase\_blackbox\_logs

Erase logs from the blackbox memory.

### set\_craft\_name

Set the craft name stored in FC.

### save\_settings

Save changes to EEPROM.

### backup\_configuration

Export current config as CLI commands for backup.

### send\_cli\_command

Send raw CLI commands to the FC.