betaflight-mcp

Betaflight MCP

An MCP (Model Context Protocol) server that exposes Betaflight flight controller control to AI assistants such as Claude. It communicates with the FC over a serial connection using the MSP binary protocol and the Betaflight CLI text interface. Use it at your own risk — it can send any command the CLI allows, including ones that may cause crashes, flyaways, or other unsafe conditions if misused. Always review tool actions before approving them in Claude.

Compatibility

• Betaflight firmware v2025.12 or later

Features

• Real-time sensor reads — attitude, IMU, GPS, RC channels, motors, battery
• Full CLI access — feature flags, variable get/set, dump/diff, save, defaults
• Auto-generated variable tools: ~750 CLI-configurable variables each exposed as a get_<name> / set_<name> tool pair, derived from the Betaflight firmware source
• Expert PID tuning skill — automatically activates in Claude Code when tuning topics come up

Claude Code Plugin

This repo ships a Claude Code plugin in the plugin/ directory, which bundles:

• The PID tuning skill — activates automatically when you mention Betaflight, PID tuning, filter tuning, propwash, oscillations, etc.
• The MCP server config — connects Claude Code to the betaflight-mcp server

Install the plugin

1. Build the server (required before first use):

pnpm install
pnpm build

2. Add the local marketplace:

claude plugin marketplace add /path/to/betaflight-mcp
claude plugin install betaflight-mcp@betaflight-mcp

Replace /path/to/betaflight-mcp with the absolute path to your cloned repository (the repo root, not the plugin/ subdirectory).

3. Configure the server path and whitelist read tools — run the setup script:

pnpm run setup
pnpm whitelist-reads

This replaces the placeholder in the cached plugin's .mcp.json with the absolute path to dist/server.js on your machine. The repo's plugin/.mcp.json is left untouched so the placeholder stays clean for git. Restart Claude Code afterwards. The whitelist script adds all read-only MCP tools to the allowed tools list of Claude, so you don't have to manually approve them all the time. Write access tools are never whitelisted by default for safety.

Updating the plugin

After pulling new changes from the repo, rebuild and reinstall the plugin:

pnpm build
claude plugin uninstall betaflight-mcp@betaflight-mcp
claude plugin install betaflight-mcp@betaflight-mcp

Then re-run the setup and whitelist scripts:

pnpm run setup
pnpm whitelist-reads

Claude Desktop users: The plugin system is a Claude Code (CLI) feature and is not available in Claude Desktop. Claude Desktop users configure the MCP server manually via claude_desktop_config.json (see platform-specific setup below) — this gives full access to all ~1500 tools. The PID tuning skill does not auto-activate in Claude Desktop; as a workaround, create a Claude Project and attach plugin/skills/betaflight-pid-tuning/SKILL.md as project knowledge so it is always in context.

CLI commands and variables as MCP tools

All CLI-configurable variables are exposed as individual get_<name> / set_<name> tool pairs, auto-generated from the Betaflight firmware source (settings.c, ~750 variables), enriched with descriptions from the CLI reference docs.

Run pnpm generate to regenerate src/generated/variables.ts after a Betaflight release.

Development

pnpm generate      # Re-fetch firmware sources + Cli.md, regenerate src/generated/variables.ts
pnpm dev           # Run directly via tsx (no build step)
pnpm build         # pnpm generate (prebuild) → tsc → dist/
pnpm typecheck     # Type-check without emitting
pnpm lint          # ESLint over src/

Architecture

Claude Desktop
    │  stdio (MCP JSON-RPC)
    ▼
betaflight-mcp
    ├── MSP binary protocol  ←→  FC (real-time sensor reads)
    └── CLI text interface   ←→  FC (configuration, variables)

The server maintains a single serial connection shared between the MSP client and the CLI client, serialised via a FIFO mutex so commands never interleave on the wire.

Using with Claude Desktop

The server communicates over stdio — Claude Desktop spawns it as a subprocess and pipes stdin/stdout for MCP JSON-RPC. There is no HTTP port.

Choose the approach that matches your operating system.

Windows — Native (recommended)

Docker Desktop on Windows uses a WSL2 Linux VM. Passing COM ports into a Linux container requires USBIPD-WIN and is non-trivial. Running the server natively with Node.js is the simpler path on Windows.

Prerequisites