Inav MCP

iNAV MCP Server

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.

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.

---

Requirements

• Python 3.10+
• An iNAV flight controller (developed against iNAV 8.x/9.x) connected over USB
• The serial port the FC enumerates as (e.g. COM3 on Windows, /dev/ttyACM0 on Linux)

Install

From PyPI (once the first release is published):

pip install inav-mcp

From source (for development, or to run the latest unreleased code):

# from the repo root

python -m venv .venv .venv/Scripts/python -m pip install -e . # Windows

source .venv/bin/activate && pip install -e . # Linux/macOS

For development (tests):

.venv/Scripts/python -m pip install -e ".[dev]"

Try it without a flight controller

You don't need any hardware to confirm the project works — the test suite runs fully offline (no FC required):

.venv/Scripts/python -m pytest        # Windows

.venv/bin/pytest # Linux/macOS

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.

Register with Claude

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:

{

"mcpServers": { "inav": { "command": "C:\\path\\to\\inav-mcp\\.venv\\Scripts\\python.exe", "args": ["-m", "inav_mcp.server"], "cwd": "C:\\path\\to\\inav-mcp" } } }

Linux / macOS:

{

"mcpServers": { "inav": { "command": "/path/to/inav-mcp/.venv/bin/python", "args": ["-m", "inav_mcp.server"], "cwd": "/path/to/inav-mcp" } } }

The server speaks MCP over stdio. You can also run it directly with the installed entry point inav-mcp.

---

Typical workflows

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."

---

Tools (35)

Connection & identity

Hardware setup

Flight modes & switches

Diagnostics

Bench tests & calibration

Navigation & tuning

Config management

Resources

• 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.

---

Safety model

1. Props-off gate — 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.
2. Armed guard — all writes (and motor tests / calibrations) refuse if the FC reports armed.
3. Auto-backup before every write; the backup path is returned.
4. Dry-run by default — writes return the exact commands; confirm=True applies.
5. Read-back verify — after applying, settings are re-read and mismatches flagged.
6. `save` = reboot — save_and_reboot warns and marks the connection stale.
7. No receiver-mode changes — the FC is never switched to MSP-RX.

Reboot model — why batching matters

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:

• Reads prefer MSP, which never reboots. 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.
• Writes are atomic and batch internally. Each write tool (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).
• Resilient reconnect. After a reboot the reconnect waits a short settle, then polls with backoff; if the original COM port doesn't return it scans for a re-enumerated one, and if the board came back in DFU/bootloader mode it says so and tells you to power-cycle (USB unplug/replug) rather than hanging.

How it works

• Single serial handle shared between MSP and CLI modes (connection.py), tracked by a mode state machine. Never two handles on one port.
• CLI-first writes — the CLI is stable across firmware versions; MSP command IDs can drift. A thin MSP v1/v2 codec (msp.py) handles only the live binary reads (status, RC, attitude, analog, GPS, sensor health, mode ranges, box maps).
• Box IDs are resolved at runtime via MSP_BOXNAMES + MSP_BOXIDS — never hardcoded.
• Arming flags are decoded from knowledge/arming_flags.json, calibrated to iNAV 8.x/9.x bit positions. The table declares its calibrated major versions, and