io.github.starlordz12Published by GitHub account starlordz12v1.0.0Updated Nov 3, 2026
MCP server for iNAV flight-controller configuration and diagnostics
Configures, diagnoses and troubleshoots an iNAV flight controller over USB serial, mainly for fixed-wing and flying-wing aircraft.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
[CI] [License: MIT] [Python] [MCP] [PyPI]
An MCP server that lets Claude configure, diagnose, and troubleshoot an iNAV flight controller over USB — built primarily for flying wings (elevon FPV wings like the TBS Chupito and Mojito), and also for conventional fixed-wing planes.
It talks to the FC through a single serial connection, using the iNAV CLI for configuration writes and a small built-in MSP codec for live/binary reads. Every write is dry-run by default, auto-backs-up first, refuses while the board is armed, and reads back to verify.
[iNAV MCP session — Claude finding the flight controller and reading its status over USB]
Recorded against a live iNAV 6.1.0 flight controller over USB.
⚠️ Safety: Always remove props from the aircraft before any motor test. This tool never switches the FC into MSP-RX mode and never arms the aircraft.
COM3 on Windows, /dev/ttyACM0 on Linux)From PyPI (once the first release is published):
From source (for development, or to run the latest unreleased code):
For development (tests):
You don't need any hardware to confirm the project works — the test suite runs fully offline (no FC required):
All 186 tests should pass. To actually use the server, though, you need a flight controller flashed with iNAV firmware (developed against iNAV 8.x/9.x) connected over USB — without one, the connection tools have nothing to talk to.
Add the server to your Claude (Code or Desktop) MCP config
(~/.claude/settings.json or the Claude Desktop config). Replace the paths
below with wherever you cloned this repo — the command points at the Python
inside your .venv, and cwd is the repo root.
Windows:
Linux / macOS:
The server speaks MCP over stdio. You can also run it directly with the
installed entry point inav-mcp.
The server ships prompts that walk Claude through the common jobs — just pick one:
new_fixed_wing_setup — gather hardware details → define_aircraft → review → apply.troubleshoot_no_arm — decode arming-prevention flags → guided fixes.configure_modes — identify switches from live RC → suggest a layout → assign modes.Or drive it conversationally, e.g.:
"Connect to my FC on COM3 and tell me why it won't arm."
"Set up a 4S flying wing on DSHOT600, then show me the commands before applying."
inav://modes-reference — iNAV mode glossary with fixed-wing relevance.inav://current-profile — the declared aircraft profile + generated plan.inav://last-backup — the most recent diff all backup.test_motor() and any live motor command via cli(...) require props_removed=True (the generic write-confirm cannot bypass it), refuse while the board is armed, and are never saved. test_motor() also clamps throttle/duration and always commands the motor back to stop.confirm=True applies.save = reboot — save_and_reboot warns and marks the connection stale.On iNAV, leaving the CLI always reboots the FC — both save (persist to
EEPROM) and exit (discard changes) trigger a reboot, after which the USB VCP
re-enumerates and we reconnect (~6–8 s, surfaced as reboot_seconds). So every
CLI round-trip costs one reboot, including read-only ones (get, diff,
dump, version). There is no way to read over the CLI without that reboot —
the only lever is to do fewer CLI sessions.
What this server does to keep reboot churn down:
get_status, read_rc_channels,
read_sensors, read_gps, list_flight_modes, why_wont_it_arm, diagnose,
and the armed-guard all read structured data over MSP — zero reboots. Only data
that's CLI-only (diff all, get failsafe, PID/rate/filter gets) pays a reboot.apply_aircraft_setup, set_flight_mode, assign_switch, set_pid,
set_failsafe, restore_config, …) opens one CLI session: backup → apply
all commands → save → reboot once. Multiple settings = one reboot.cli_batch() for ad-hoc runs. Instead of calling cli() in a loop (one
reboot per command — the cadence that can knock a board into DFU), pass a
list to cli_batch(): one session, one reboot. Read-only batches exit without
saving; write batches back up and save once (rolling back if any command is
rejected).connection.py),
tracked by a mode state machine. Never two handles on one port.msp.py) handles only the live binary
reads (status, RC, attitude, analog, GPS, sensor health, mode ranges, box maps).MSP_BOXNAMES + MSP_BOXIDS — never hardcoded.knowledge/arming_flags.json, calibrated to
iNAV 8.x/9.x bit positions. The table declares its calibrated major versions, and
connect() / board_info() / why_wont_it_arm() / diagnose() warn when the
connected firmware is outside that range (bit positions shift between majors, so
flag names may be mislabelled even though the raw flag value is correct).The suite covers the MSP codec round-trips, CLI response parsing, the diagnostic rule engine, offline profile/command generation, mode-range read-modify-write logic (against a mock connection), and resource/prompt registration.
Project layout:
Release history is in CHANGELOG.md.
Complete, signature-accurate list — regenerate after changing tools with
python -m tools.gen_readme_tools (a test fails if this drifts):
35 tools — auto-generated by tools/gen_readme_tools.py; do not edit by hand.
This is an actively developed project — more tools are on the way. Areas currently in progress or planned:
Have a flight-controller task you wish Claude could do? Open an issue and request a tool — feature requests directly shape what gets built next.
If this saved you a bench session, here's how to help the project grow:
pytest, 186 tests), so
you can add and verify a new tool without any hardware on the bench.Hardware-tested on iNAV 6.1.0 (SpeedyBee F405 Wing). The arming-flag decoder is calibrated for iNAV 8.x/9.x and warns when it sees another major version. Results and PRs from other targets and firmware versions are especially welcome.
MIT. This project ships its own MSP codec and does not import GPL libraries (uNAVlib / YAMSPy) at runtime, keeping it permissively licensed.
Source: README.md at commit 3140c77
List all available serial ports. Use this to find the COM port (Windows) or /dev/tty* (Linux/macOS) for the FC. Plug in the FC, run this, and look for a new entry (often labelled 'STM32' or 'CP210x' for iNAV boards).
Takes no parameters.
Open the serial connection to the FC and return board identity. Args: port: Serial port, e.g. 'COM3' (Windows) or '/dev/ttyACM0' (Linux). baud: Baud rate (default 115200 — matches iNAV's USB VCP default). Returns board variant, firmware version, target name, API version, build info, and a summary of detected sensors.
baudportrequiredClose the serial connection to the FC.
Takes no parameters.
Read flight-controller identity over MSP. Returns: FC variant (e.g. 'INAV'), firmware version, board/target name, API version, build date/time/git revision, and sensors detected. Requires an active connection (call connect first).
Takes no parameters.
Auto-detect which serial port has a flight controller, so you don't guess. Briefly opens each likely USB-serial port and asks for MSP identity; returns the ports that answered as an FC (variant + firmware). Then call connect(port). Args: baud: Baud to probe at (default 115200, iNAV's USB VCP default). probe_all: If True, probe EVERY serial port; otherwise only USB-serial-looking ones (safer — avoids poking unrelated devices like Bluetooth/modems).
baudprobe_allSave the current FC config to a timestamped backup file. Runs 'diff all' in the CLI and writes the output to ./backups/<timestamp>.txt. NOTE: on iNAV, leaving the CLI reboots the FC, so this reboots and then auto-reconnects (~7s). The result includes 'rebooted': True. Args: label: Optional suffix added to the filename for easy identification.
labelRestore FC config by replaying a backup file's CLI commands, then save+reboot. On iNAV this is atomic: a pre-restore backup is taken, the file's commands are replayed in one CLI session, then SAVED to EEPROM and the FC reboots (we reconnect). If any line errors, all changes are rolled back. Args: path: Path to a backup file (as returned by backup_config). confirm: Must be True to apply. Dry-run by default.
pathrequiredconfirmRaw CLI escape hatch — run any iNAV CLI command directly. Read-only commands (diff, get, status, dump, tasks, help, version) run and the FC reboots on CLI exit (auto-reconnected). Write commands (set, aux, feature, smix, ...) require confirm_for_writes=True and are SAVED (persist + reboot), since on iNAV exiting CLI without save discards changes. SAFETY — motor commands: a 'motor ...' command drives a LIVE motor output and can spin a propeller. It is gated separately from ordinary writes: it requires props_removed=True (NOT confirm_for_writes), refuses if the board is armed, and is NEVER saved — it's a momentary bench test that stops when the FC reboots on CLI exit. Prefer the dedicated write tools (they back up and verify). Use this for one-off commands the other tools don't cover. Args: command: The CLI command to run (without trailing newline). confirm_for_writes: Set True to allow (and persist) write commands. props_removed: Set True to allow a live 'motor' test — ONLY after physically removing all propellers from the aircraft.
commandrequiredprops_removedconfirm_for_writesRun MANY CLI commands in ONE CLI session — a single reboot for the whole batch. On iNAV, leaving the CLI ALWAYS reboots the FC, so every separate cli() call costs a full reboot + USB re-enumeration + reconnect (~7s). Doing a run of commands one cli() call at a time means one reboot PER command — the rapid reboot cadence is disruptive and can even knock the board into DFU/bootloader mode. This collapses N commands into ONE session = ONE reboot. Prefer it for any ad-hoc multi-command work (several `get` reads, or several `set` writes). (The dedicated write tools — apply_aircraft_setup, set_flight_mode, etc. — already batch internally; this is the escape hatch for everything else.) Behaviour: - All read-only batch (get/diff/dump/status/tasks/version): the session exits WITHOUT saving — no EEPROM write, nothing persists. Still one reboot (unavoidable on iNAV), but reads are free of a save. - Any write (set/aux/feature/…): requires confirm_for_writes=True; a backup is taken first and the whole batch is SAVED once at the end (persist + reboot). If ANY command is rejected by the FC, the batch exits WITHOUT saving so nothing partial persists (all-or-nothing). - Live `motor` commands and session-control verbs (save/exit/batch) are rejected up front — motor tests must never be saved (use cli(..., props_removed=True) / test_motor()), and the batch manages save/exit itself. Args: commands: Ordered list of CLI commands to run in one session. confirm_for_writes: Set True to run and persist a batch containing writes. Returns per-command output, whether it saved, the backup path (if it wrote), and the measured reboot/reconnect seconds for the single reboot.
commandsrequiredconfirm_for_writesSave the running config to EEPROM and reboot the FC. Takes a backup, then 'save' (persist + reboot), then auto-reconnects (~7s). NOTE: the dedicated write tools already save automatically on iNAV, so you rarely need this — it's for persisting changes made via the raw cli() reads or to force a clean reboot. Args: confirm: Must be True to proceed. Dry-run by default.
confirmRead live RC channel values via MSP. Returns up to 16 channel values in microseconds (988–2012 µs typical). Core UX: flip a switch and watch which channel value changes — that's the aux channel to use when assigning flight modes.
Takes no parameters.
Read live sensor values: attitude, per-sensor health, and analog (battery). Good for a quick sanity pass before flying: - Attitude should read ~0°/0° when the aircraft is level. - All required sensors (gyro, acc) should report OK. - Battery voltage should match your pack's cell count.
Takes no parameters.
Read FC status via both MSP and CLI. Returns MSP_STATUS data (cycle time, sensor bits, CPU load, arming flags) plus the human-readable output of the CLI 'status' and 'tasks' commands.
Takes no parameters.
List all available flight modes and their current switch assignments. Returns: - all_modes: every mode the FC knows about (id + name + assigned flag) - assigned_modes: which modes are on which aux channel and range - unassigned_modes: mode names with no switch assignment yet - arm_assigned: bool — critical to know before first flight Tip: call read_rc_channels() to identify which channel your switches use, then use assign_switch() to map modes to them.
Takes no parameters.
Decode the FC's arming-prevention flags into plain English. This is the #1 question from new iNAV users. Each set bit is mapped to: - A flag name - A plain-language reason - A concrete fix Also checks whether ARM mode is assigned to a switch.
Takes no parameters.
Full diagnostic sweep — the flagship troubleshooter. Collects: arming flags, sensor health, RC channels, battery, GPS, attitude, and mode assignments. Runs all diagnostic rules and returns a prioritized problem list with concrete fixes for each issue found. Use this when 'something is wrong but I'm not sure what.'
Takes no parameters.
Define the aircraft hardware profile and generate a configuration plan. This is an OFFLINE planner — no FC connection required. Call it first to review the generated CLI commands, then call apply_aircraft_setup() to apply. Args: name: A descriptive name for this aircraft (e.g., "My FPV Wing"). wing_type: One of: flying_wing, conventional, vtail, twin_tail, delta. esc_protocol: One of: DSHOT600, DSHOT300, DSHOT150, MULTISHOT, ONESHOT125, PWM. cells: LiPo battery cell count (e.g. 4 for 4S). fc_target: Optional FC board name (e.g. MATEKF405). Used for target hints. motor_kv: Optional motor KV rating (informational only). motor_poles: Motor pole count for RPM telemetry (default 14; verify with your motor). servo_count: Optional total servo count (informational). notes: Free text notes to store with the profile. Returns a plan dict with: - profile: the stored profile - commands: the CLI commands to apply - summary: human-readable description - warnings: things to verify before/after applying
namerequiredcellsrequirednotesmotor_kvfc_targetwing_typerequiredmotor_polesservo_countesc_protocolrequiredReturn the currently declared aircraft profile. Call define_aircraft() first to set a profile.
Takes no parameters.
Apply the declared aircraft profile to the FC, then save and reboot. On iNAV this is an ATOMIC operation: the commands are applied in one CLI session, backed up first, then SAVED to EEPROM (the only way changes persist) and the FC reboots. We reconnect automatically and verify by read-back. If any command fails, ALL changes are rolled back (nothing is saved). Gates: - A profile must be defined via define_aircraft(). - Connected and not armed. - confirm=True required (dry-run by default). Args: confirm: True to apply+save+reboot. Default False = dry-run (shows commands).
confirmCompare the FC's actual configuration against the declared aircraft profile. Runs 'diff all' via CLI, parses key settings, and reports mismatches against the profile declared with define_aircraft(). Also checks if ARM mode is assigned to a switch. Useful after apply_aircraft_setup() or to sanity-check a partially configured FC.
Takes no parameters.
Recommend a fixed-wing flight-mode/switch layout. Pure knowledge — no FC needed. Suggests which switches to use for ARM, flight modes (ANGLE/HORIZON/MANUAL), and (with GPS) NAV RTH / NAV LAUNCH, with the exact aux channels and µs ranges. Args: skill_level: beginner | intermediate | advanced (tailors the advice). num_switches: How many spare switches you have available. has_gps: True if a GPS module is installed (enables RTH suggestion). Returns a layout plan you can hand to assign_switch() to apply.
has_gpsskill_levelnum_switchesAssign a flight mode to an aux channel range (read-modify-write via CLI 'aux'). Finds an existing slot for this mode+channel (to modify) or the first free slot (to create), then writes the assignment. Dry-run by default. Gates: connected, not armed, auto-backup before write. Requires confirm=True to apply. Args: mode_name: Exact mode name as shown by list_flight_modes (e.g. "ANGLE", "NAV RTH"). aux_channel: 1-based AUX number (1 = AUX1 = RC channel 5), matching list_flight_modes. range_low: Range start in µs (900–2100). range_high: Range end in µs (must be > range_low, ≤ 2100). confirm: True to apply. Default False = dry-run (returns the command only).
confirmmode_namerequiredrange_lowrequiredrange_highrequiredaux_channelrequiredMap a multi-position switch's detents to flight modes in one call. Computes the µs range for each detent and writes one 'aux' assignment per mode. Dry-run by default. Gates: connected, not armed, auto-backup before write. Args: switch_channel: 1-based AUX number the switch is on (1 = AUX1 = RC channel 5). switch_positions: Number of detents on the switch: 2, 3, or 6. mode_per_position: Map of position → mode name. Position keys may be "low"/"mid"/"high" (for 2/3-pos) or "1".."N" / "pos1".., e.g. {"low": "ANGLE", "mid": "HORIZON", "high": "MANUAL"}. confirm: True to apply. Default False = dry-run.
confirmswitch_channelrequiredswitch_positionsrequiredmode_per_positionrequiredRemove all switch assignments for a flight mode (disables its slots via CLI 'aux'). Dry-run by default. Gates: connected, not armed, auto-backup before write. Args: mode_name: Exact mode name (e.g. "HORIZON", "NAV RTH"). confirm: True to apply. Default False = dry-run.
confirmmode_namerequiredSpin ONE motor briefly for a bench test (direction / wiring / response). ⚠ DANGER: this drives a LIVE motor output. REMOVE ALL PROPELLERS FIRST. Safety gates (enforced in code): - props_removed=True is REQUIRED (refuses otherwise), - refuses if the FC reports armed, - confirm=True is REQUIRED (dry-run preview otherwise), - throttle clamped to 1000–2000 µs, duration clamped to 0.2–5.0 s, - the motor is ALWAYS commanded back to stop (1000 µs) when the test ends. The override is live (MSP, not saved); it also stops if the FC reboots or loses power. Args: motor: 1-based motor number (1 = motor 1). Only this motor spins; all others are held at 1000 µs (stop). throttle_us: Output in µs (1000 = stop, ~1100 = gentle, 2000 = full). Keep it LOW for a direction check. duration_s: How long to hold the output (0.2–5.0 s). props_removed: MUST be True — confirms props are physically removed. confirm: MUST be True to actually run.
motorrequiredconfirmduration_sthrottle_usprops_removedCalibrate the accelerometer (zero-level). Fixes most 'not level' / 'accel not calibrated' arming blocks. Sends MSP_ACC_CALIBRATION; iNAV samples for ~2s and saves to EEPROM automatically (no reboot). BEFORE running: set the board/aircraft on a LEVEL surface in its normal flight orientation and DO NOT move it until this returns. Gates: connected, not armed, confirm=True (dry-run otherwise).
confirmCalibrate the compass (magnetometer). Only useful if a compass is installed. Sends MSP_MAG_CALIBRATION; you then have ~30s to rotate the aircraft 360° around all three axes. iNAV saves the result automatically. Gates: connected, not armed, confirm=True (dry-run otherwise).
confirmRead and explain the failsafe configuration (what happens on RC loss). Reads all `failsafe_*` settings via CLI `get failsafe`, summarises the RC-loss procedure in plain English, and flags risky setups (procedure NONE; RTH without GPS). NOTE: reads over CLI; exiting CLI reboots the FC, so this reboots and reconnects (~7s).
Takes no parameters.
Set the core failsafe behaviour (atomic CLI write: backup → apply → save+reboot). Only the arguments you pass are changed; dry-run by default. For other failsafe_* knobs (distances, angles) use cli('set failsafe_... = N', confirm_for_writes=True). Args: procedure: RC-loss action — one of DROP | LAND | SET-THR | RTH | NONE. The exact accepted tokens depend on firmware; an invalid value is rejected by the FC and the whole write is rolled back. throttle_us: failsafe_throttle in µs (used by SET-THR / LAND). Clamped 1000–2000. delay_s: Guard time after RC loss before failsafe triggers (failsafe_delay). iNAV stores this in 0.1 s units, so this is converted ×10. off_delay_s: Time the failsafe stage runs before the motor is killed (failsafe_off_delay), also 0.1 s units (×10). confirm: True to apply (saves + reboots). Dry-run otherwise. Gates: connected, not armed, auto-backup. RTH without GPS will not work — use DROP/LAND.
confirmdelay_sprocedureoff_delay_sthrottle_usList saved config backups under ./backups/, newest first. No FC needed. Returns each backup's path, modified time, size, line count, and label — so you can pick one to replay with restore_config(path).
Takes no parameters.
Live GPS status: fix type, satellites, position, speed, HDOP + nav-readiness. Read-only (MSP_RAW_GPS, no reboot). Use this before relying on RTH or any position-holding navigation mode.
Takes no parameters.
Enable the GPS feature and set the receiver provider / SBAS (atomic CLI write). Args: provider: GPS provider token — e.g. UBLOX | NMEA | MSP (the FC validates it). sbas: Optional SBAS mode — AUTO | EGNOS | WAAS | MSAS | GAGAN | NONE. confirm: True to apply (save+reboot). Dry-run otherwise. Gates: connected, not armed, auto-backup. After applying, give the GPS time to acquire satellites and check read_gps().
sbasconfirmproviderSet core fixed-wing navigation / RTH parameters (atomic CLI write). Only the arguments you pass are changed. Dry-run by default. Args: rth_altitude_m: Return-to-home altitude, metres (nav_rth_altitude, stored cm). rth_climb_first: Climb to RTH altitude before heading home (nav_rth_climb_first). rth_allow_landing: NEVER | ALWAYS | FS_ONLY (nav_rth_allow_landing). loiter_radius_m: Fixed-wing loiter radius, metres (nav_fw_loiter_radius, stored cm). confirm: True to apply (save+reboot). Dry-run otherwise. Gates: connected, not armed, auto-backup. RTH needs a working GPS and a home fix.
confirmrth_altitude_mloiter_radius_mrth_climb_firstrth_allow_landingRead fixed-wing PID gains, rates, and key filter cutoffs (via CLI). Returns PIDs grouped by axis, plus rate and low-pass-filter settings. NOTE: reads over CLI; exiting CLI reboots the FC, so this reboots and reconnects (~7s).
Takes no parameters.
Set fixed-wing PID gains for ONE axis (atomic CLI write). Changes only the terms you pass. Dry-run by default. Args: axis: roll | pitch | yaw. p, i, d, ff: Gains for fw_p_<axis> / fw_i_<axis> / fw_d_<axis> / fw_ff_<axis>. confirm: True to apply (save+reboot). Dry-run otherwise. ⚠ PID changes alter flight behaviour — change gradually and test carefully. Gates: connected, not armed, auto-backup.
dipffaxisrequiredconfirm90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
pip install inav-mcp# from the repo rootpython -m venv .venv.venv/Scripts/python -m pip install -e . # Windows# source .venv/bin/activate && pip install -e . # Linux/macOS.venv/Scripts/python -m pip install -e ".[dev]".venv/Scripts/python -m pytest # Windows# .venv/bin/pytest # Linux/macOS{ "mcpServers": { "inav": { "command": "C:\\path\\to\\inav-mcp\\.venv\\Scripts\\python.exe", "args": ["-m", "inav_mcp.server"], "cwd": "C:\\path\\to\\inav-mcp" } }}{ "mcpServers": { "inav": { "command": "/path/to/inav-mcp/.venv/bin/python", "args": ["-m", "inav_mcp.server"], "cwd": "/path/to/inav-mcp" } }}.venv/Scripts/python -m pytest # 186 tests, all offline (no FC needed)inav_mcp/ server.py # FastMCP app: all tools, resources, prompts connection.py # single serial handle, MSP + CLI mode switching msp.py # MSP v1/v2 codec + parsers cli.py # CLI response parsing, write-command detection modes.py # box maps, mode-range read/write, layout planner profiles.py # AircraftProfile + offline CLI command generator troubleshoot.py # diagnose() rule engine + arming-flag decode safety.py # armed guard, backup paths state.py # connection + profile singletons knowledge/ # arming_flags / modes_reference / esc_protocols / fc_targets (JSON)tests/ # offline pytest suitetools/ # gen_readme_tools.py — regenerates the tool reference belowexamples/ # flying_wing_quickstart.md — end-to-end walkthrough