inav-mcp

iNAV MCP Server

一个 MCP 服务，可让 Claude 通过 USB 配置、诊断和排查 iNAV 飞控问题。它主要面向飞翼（例如 TBS Chupito 和 Mojito 等使用升降副翼的 FPV 飞翼），也适用于常规固定翼飞机。

它通过单个串口连接与飞控通信：使用 iNAV CLI 写入配置，并通过内置的小型 MSP 编解码器读取实时数据和二进制数据。所有写入默认都以干运行方式执行，会先自动备份；飞控已解锁时会拒绝写入，并在写入后回读验证。

_{此演示使用一台通过 USB 连接、运行 iNAV 6.1.0 的飞控录制。}

⚠️ 安全提示： 对电机进行任何测试前，务必拆下飞行器的螺旋桨。 此工具绝不会将飞控切换到 MSP-RX 模式，也绝不会解锁飞行器。

---

要求

• Python 3.10+
• 一台通过 USB 连接的 iNAV 飞控（开发时使用的是 iNAV 8.x/9.x）
• 飞控枚举出的串口（例如，Windows 上的 COM3，Linux 上的 /dev/ttyACM0）

安装

从 PyPI 安装（首个版本发布后）：

pip install inav-mcp

从源代码安装（用于开发或运行最新的未发布代码）：

# 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

开发环境（测试）：

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

无飞控也可试用

无需任何硬件即可确认项目能正常运行——测试套件可完全离线运行（不需要飞控）：

.venv/Scripts/python -m pytest        # Windows
# .venv/bin/pytest                     # Linux/macOS

所有 186 项测试都应通过。不过，若要实际使用该服务，你需要通过 USB 连接一台刷入 iNAV 固件（开发时使用的是 iNAV 8.x/9.x）的飞控；没有飞控，连接工具就没有可通信的对象。

注册到 Claude

将此服务添加到 Claude（Code 或 Desktop）的 MCP 配置中 （~/.claude/settings.json 或 Claude Desktop 配置文件）。请将下方的路径替换为你克隆此仓库的位置——command 指向 .venv 中的 Python，cwd 则指向仓库根目录。

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

此服务通过 stdio 使用 MCP 通信。你也可以通过已安装的入口点 inav-mcp 直接运行。

---

典型工作流

此服务附带了一些提示词，可引导 Claude 完成常见任务——只需选择一个：

• new_fixed_wing_setup — 收集硬件信息 → define_aircraft → 审核 → 应用。
• troubleshoot_no_arm — 解读解锁阻止标志 → 引导完成修复。
• configure_modes — 根据实时 RC 识别开关 → 推荐布局 → 分配模式。

你也可以通过对话来操作，例如：

“连接到我在 COM3 上的飞控，告诉我它为什么无法解锁。”

“将一架 4S 飞翼配置为 DSHOT600，然后在应用前显示命令。”

---

工具（35 个）

连接与身份信息

工具	功能
list_serial_ports()	列出可用串口。
find_fc(baud=115200, probe_all=False)	通过探测 MSP 身份自动检测哪个端口连接了飞控——无需猜测端口。
connect(port, baud=115200)	打开飞控连接并返回板卡身份信息。
disconnect()	关闭连接。
board_info()	飞控变体、固件版本、目标、API 版本及传感器。

硬件设置

工具	功能
define_aircraft(name, wing_type, esc_protocol, cells, …)	离线规划器——存储配置并生成 CLI 配置计划。
get_aircraft_profile()	当前声明的配置和计划。
apply_aircraft_setup(confirm=False)	应用计划（设有门控：未解锁、自动备份、回读验证）。在 iNAV 上，应用操作必然会保存并重启。
check_config()	diff all，并根据声明的配置进行 lint 检查和 ARM 检查。

飞行模式和开关

工具	功能
suggest_mode_layout(skill_level, num_switches, has_gps=False)	推荐固定翼开关／模式布局（离线）。
set_flight_mode(mode_name, aux_channel, range_low, range_high, confirm=False)	将一个模式分配给一个辅助通道范围。
assign_switch(switch_channel, switch_positions, mode_per_position, confirm=False)	一次调用即可映射整个 2／3／6 挡开关。
clear_flight_mode(mode_name, confirm=False)	移除某个模式的开关分配。

诊断

工具	功能
diagnose()	全面检查：解锁、传感器、RC、电池、GPS → 按优先级排列的修复建议。
why_wont_it_arm()	将阻止解锁的标志解读为通俗原因和修复方法。
read_rc_channels()	实时 RC 通道值——拨动开关，查看哪个通道发生变化。
read_sensors()	实时姿态、各传感器状态和电池信息。
get_status()	MSP 状态以及 CLI status／tasks。
list_flight_modes()	所有模式及其当前开关分配。
check_failsafe()	读取 failsafe_* 设置，说明 RC 信号丢失时的流程，并标记有风险的配置（例如没有 GPS 却设置了 RTH）。

台架测试和校准

工具	功能
test_motor(motor, throttle_us=1100, duration_s=2.0, props_removed=False, confirm=False)	短暂转动一个电机。严格设有门控：必须设置 props_removed=True 和 confirm=True；飞行器处于解锁状态时会拒绝执行，并且总会自动停止。（没有 test_servo——iNAV 不支持实时舵机覆盖；请使用 TX 摇杆和 read_rc_channels() 检查舵面。）
calibrate_accelerometer(confirm=False)	将加速度计调零（飞控板保持水平且静止）。可修复大多数“未水平”导致的解锁阻止问题。
calibrate_magnetometer(confirm=False)	校准罗盘（将飞行器旋转约 30 秒）。

导航和调参

工具	功能
read_gps()	实时 GPS 定位／卫星数／位置，以及导航就绪状态评估（只读）。
configure_gps(provider="UBLOX", sbas=None, confirm=False)	启用 GPS 功能并设置 provider／SBAS。
set_nav(rth_altitude_m=None, rth_climb_first=None, rth_allow_landing=None, loiter_radius_m=None, confirm=False)	设置固定翼 RTH 高度／优先爬升／允许降落／盘旋半径。
read_tuning()	读取固定翼 PID 增益、速率和滤波器截止频率。
set_pid(axis, p=None, i=None, d=None, ff=None, confirm=False)	为一个轴设置固定翼 P／I／D／FF 增益。

配置管理

工具	功能
backup_config(label=None)	将 diff all 保存到 ./backups/ 下带时间戳的文件中。
list_backups()	列出已保存的备份（路径、时间、大小、标签），按时间从新到旧排列。
restore_config(path, confirm=False)	通过 CLI 重放已保存的备份。
set_failsafe(procedure=None, throttle_us=None, confirm=False)	设置 RC 信号丢失时的流程／油门（原子写入；飞控会验证流程标记）。
cli(command, confirm_for_writes=False, props_removed=False)	原始 CLI 逃生口（一个命令，一次重启）。写入操作需要 confirm_for_writes；实时 motor 测试需要 props_removed=True，且不会保存。
cli_batch(commands, confirm_for_writes=False)	在一次会话中运行多个 CLI 命令 → 一次重启。只读批处理会退出而不保存；写入批处理会先备份再保存一次（如果有命令被拒绝，则回滚）。拒绝 motor／save／exit 命令。
save_and_reboot(confirm=False)	保存到 EEPROM 并重启（会将连接标记为过期）。

资源

• inav://modes-reference — iNAV 模式术语表，包含与固定翼相关的内容。
• inav://current-profile — 已声明的飞行器配置文件和生成的计划。
• inav://last-backup — 最近一次 diff all 备份。

---

安全模型

1. 螺旋桨拆除保护门 — test_motor() 和通过 cli(...) 执行的任何实时 motor 命令都要求 props_removed=True（通用写入确认无法绕过此要求）；如果飞控处于解锁状态，则拒绝执行，并且绝不会保存设置。test_motor() 还会限制油门和持续时间，并始终命令电机停止。
2. 解锁状态保护 — 如果飞控报告处于解锁状态，则拒绝所有写入（以及电机测试／校准）。
3. 每次写入前自动备份；并返回备份路径。
4. 默认试运行 — 写入操作会返回确切的命令；设置 confirm=True 后才会应用。
5. 回读验证 — 应用后重新读取设置，并标记不匹配项。
6. save = 重启 — save_and_reboot 会发出警告，并将连接标记为过期。
7. 不更改接收机模式 — 飞控绝不会切换到 MSP-RX。

重启模型 — 为什么批处理很重要

在 iNAV 中，退出 CLI 总会重启飞控 — 无论是 save（持久化到 EEPROM）还是 exit（放弃更改），都会触发重启；之后 USB VCP 会重新枚举，我们再重新连接（约 6–8 s，通过 reboot_seconds 显示）。因此，每次 CLI 往返都会导致一次重启，包括只读操作（get、diff、 dump、version）。没有办法在不重启的情况下通过 CLI 读取 — 唯一的办法是减少 CLI 会话次数。

此服务会通过以下方式减少重启次数：

• 读取优先使用不会导致重启的 MSP。 get_status、read_rc_channels、 read_sensors、read_gps、list_flight_modes、why_wont_it_arm、diagnose 和解锁状态保护逻辑都会通过 MSP 读取结构化数据 — 零重启。只有 CLI 独有的数据（diff all、get failsafe、PID／速率／滤波器的 get）才会 导致重启。
• 写入是原子操作，并在内部批处理。 每个写入工具 （apply_aircraft_setup、set_flight_mode、assign_switch、set_pid、 set_failsafe、restore_config 等）只会打开一个 CLI 会话：备份 → 应用 所有命令 → 保存 → 重启一次。多个设置只需重启一次。
• 使用 cli_batch() 执行临时命令。 不要循环调用 cli()（每条命令 都会重启一次 — 这种频率可能会让飞控进入 DFU）；改为向 cli_batch() 传入 命令列表：一个会话，一次重启。只读批处理会在不保存的情况下执行 exit；写入批处理会先 备份再执行一次 save（如果有命令被拒绝，则回滚）。
• 弹性重连。 重启后，重连会等待设备短暂稳定，然后采用退避策略轮询；如果 原 COM 端口未恢复，则会扫描重新枚举的端口；如果飞控以 DFU／引导加载程序模式重新启动， 会明确告知你，并提示断电重启（拔下再重新插入 USB），而不是一直等待。

工作原理

• MSP 和 CLI 模式共用一个串行句柄（connection.py），由 mode 状态机跟踪。一个端口绝不会同时使用两个句柄。
• 写入优先使用 CLI — CLI 在不同固件版本间表现稳定；MSP 命令 ID 可能变化。精简的 MSP v1/v2 编解码器（msp.py）仅处理实时二进制 读取（状态、RC、姿态、模拟数据、GPS、传感器健康状态、模式范围、盒子映射）。
• 盒子 ID 在运行时解析，通过 MSP_BOXNAMES + MSP_BOXIDS 获取 — 绝不硬编码。
• 解锁标志从 knowledge/arming_flags.json 解码，并按 iNAV 8.x/9.x 的位位置校准。该表会注明已校准的主版本；当连接的固件版本超出该范围时， connect() / board_info() / why_wont_it_arm() / diagnose() 会发出警告 （主版本之间的位位置会变化，因此即使原始标志值正确，标志名称也可能标错）。

开发

.venv/Scripts/python -m pytest          # 186 tests, all offline (no FC needed)

测试套件涵盖 MSP 编解码往返、CLI 响应解析、诊断规则引擎、离线配置文件／命令生成、模式范围的读取-修改-写入逻辑（使用模拟连接），以及资源／提示词注册。

项目布局：

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 suite
tools/               # gen_readme_tools.py — regenerates the tool reference below
examples/            # flying_wing_quickstart.md — end-to-end walkthrough

发布历史请参阅 CHANGELOG.md。

完整工具参考

完整且与签名准确一致的列表——更改工具后，使用 python -m tools.gen_readme_tools 重新生成（如果内容不一致，测试会失败）：

35 个工具 — 由 tools/gen_readme_tools.py 自动生成；请勿手动编辑。

工具	描述
apply_aircraft_setup(confirm=False)	将声明的飞行器配置应用到 FC，然后保存并重启。
assign_switch(switch_channel, switch_positions, mode_per_position, confirm=False)	一次调用即可将多段开关的各档位映射到飞行模式。
backup_config(label=None)	将当前 FC 配置保存到带时间戳的备份文件中。
board_info()	通过 MSP 读取飞控身份信息。
calibrate_accelerometer(confirm=False)	校准加速度计（水平归零）。修复大多数“未水平”或“加速度计未
calibrate_magnetometer(confirm=False)	校准指南针（磁力计）。仅在安装了指南针时才有用。
check_config()	将 FC 的实际配置与声明的飞行器配置进行比较。
check_failsafe()	读取并说明失控保护配置（遥控信号丢失时会发生什么）。
clear_flight_mode(mode_name, confirm=False)	移除某个飞行模式的所有开关分配（通过 CLI 'aux' 禁用其槽位）。
cli(command, confirm_for_writes=False, props_removed=False)	原始 CLI 入口——直接运行任意 iNAV CLI 命令。
cli_batch(commands, confirm_for_writes=False)	在一个 CLI 会话中运行多个 CLI 命令——整个批次只需重启一次。
configure_gps(provider='UBLOX', sbas=None, confirm=False)	启用 GPS 功能并设置接收器供应商 / SBAS（原子 CLI 写入）。
connect(port, baud=115200)	打开与 FC 的串行连接并返回板卡身份信息。
define_aircraft(name, wing_type, esc_protocol, cells, fc_target=None, motor_kv=None, motor_poles=14, servo_count=None, notes=None)	定义飞行器硬件配置并生成配置计划。
diagnose()	全面诊断——核心故障排查工具。
disconnect()	关闭与 FC 的串行连接。
find_fc(baud=115200, probe_all=False)	自动检测哪个串行端口连接了飞控，无需猜测。
get_aircraft_profile()	返回当前声明的飞行器配置。
get_status()	通过 MSP 和 CLI 读取 FC 状态。
list_backups()	列出 ./backups/ 下保存的配置备份，按时间从新到旧排列。无需连接 FC。
list_flight_modes()	列出所有可用的飞行模式及其当前开关分配。
list_serial_ports()	列出所有可用的串行端口。
read_gps()	实时 GPS 状态：定位类型、卫星数、位置、速度、HDOP 和导航就绪情况。
read_rc_channels()	通过 MSP 读取实时 RC 通道值。
read_sensors()	读取实时传感器值：姿态、各传感器状态和模拟值（电池）。
read_tuning()	读取固定翼 PID 增益、速率和关键滤波器截止频率（通过 CLI）。
restore_config(path, confirm=False)	通过重放备份文件中的 CLI 命令恢复 FC 配置，然后保存并重启。
save_and_reboot(confirm=False)	将当前运行配置保存到 EEPROM 并重启 FC。
set_failsafe(procedure=None, throttle_us=None, delay_s=None, off_delay_s=None, confirm=False)	设置核心失控保护行为（原子 CLI 写入：备份 → 应用 → 保存并重启）。
set_flight_mode(mode_name, aux_channel, range_low, range_high, confirm=False)	将飞行模式分配给某个 AUX 通道范围（通过 CLI 'aux' 执行读取-修改-写入）。
set_nav(rth_altitude_m=None, rth_climb_first=None, rth_allow_landing=None, loiter_radius_m=None, confirm=False)	设置固定翼导航 / RTH 核心参数（原子 CLI 写入）。
set_pid(axis, p=None, i=None, d=None, ff=None, confirm=False)	设置单个轴的固定翼 PID 增益（原子 CLI 写入）。
suggest_mode_layout(skill_level='beginner', num_switches=2, has_gps=False)	推荐固定翼飞行模式 / 开关布局。纯知识功能——无需连接 FC。
test_motor(motor, throttle_us=1100, duration_s=2.0, props_removed=False, confirm=False)	短暂转动一个电机进行台架测试（方向 / 接线 / 响应）。
why_wont_it_arm()	将 FC 的禁止解锁标志解读为通俗易懂的说明。

路线图

这是一个积极开发中的项目——更多工具即将推出。目前正在开发或计划中的领域：

• 更深入的固定翼调参辅助工具（自动调参审查、飞行中速率反馈）。
• 更全面的传感器 / ESC 遥测读数。
• 为常见的设置和故障排查流程提供更多引导式提示词。

你希望 Claude 能完成某项飞控任务吗？ 提交 issue 并提出工具需求——功能请求会直接影响接下来开发的内容。

贡献与反馈

如果这个项目帮你省去了台架测试时间，以下方式可以帮助项目发展：

• ⭐ 为仓库点星，让其他 iNAV 飞手也能找到它。
• 🐛 通过 提交 issue 报告错误、固件问题或提出新工具需求。
• 🔧 欢迎提交 PR——测试套件完全离线（pytest，186 项测试），因此无需在台架上连接任何硬件，就能添加并验证新工具。

已在 iNAV 6.1.0（SpeedyBee F405 Wing）上进行硬件测试。解锁标志解码器针对 iNAV 8.x/9.x 进行了校准，并会在检测到其他主版本时发出警告。尤其欢迎针对其他目标平台和固件版本的测试结果与 PR。

许可证

MIT。本项目自带 MSP 编解码器，运行时不会导入 GPL 库（uNAVlib / YAMSPy），因此保持宽松许可证。