inav-mcp

Name: inav-mcp
Author: starlordz12

ローカル

github.com/starlordz12ゲーム・エンタメ22 日前に更新

リポジトリ

inav-mcp について

inav-mcpは、主にフライングウィング、また通常の固定翼機向けに、iNAVフライトコントローラーを設定・診断するMCPサーバーです。USBシリアルで接続し、ライブデータの読み取りと、安全確認・バックアップ・検証を伴う設定書き込みを行います。

主な機能

01フライトコントローラーの接続と識別
02固定翼機の設定計画と適用
03フライトモードとスイッチの管理
04ライブ状態と故障の診断
05バックアップ、復元、一括CLI
06安全条件付きのモーターテスト

活用シーン

01フライトコントローラーがアームできない原因の調査
02フライングウィングの設定計画と適用
03RC、センサー、GPSのライブデータ確認
04コントローラー設定のバックアップや復元

MCP 対応

stdio経由でMCPツール、リソース、プロンプトを提供し、Claude CodeやClaude DesktopなどのMCPクライアントから利用できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "starlordz12-inav": {
      "command": "uvx",
      "args": [
        "inav-mcp"
      ]
    }
  }
}

起動コマンドuvx inav-mcp

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypiinav-mcp1.0.0stdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

iNAV MCP サーバー

Claude が USB 経由で iNAV フライトコントローラーを設定、診断、トラブルシューティングできる MCP サーバーです。主にフライングウィング（TBS Chupito や Mojito などのエレボン式 FPV ウィング）向けに開発されており、一般的な固定翼機にも対応しています。

FC とは単一のシリアル接続で通信します。設定の書き込みには iNAV の CLI を、ライブデータやバイナリデータの読み取りには組み込みの小型 MSP コーデックを使用します。すべての書き込みはデフォルトでドライランとなり、事前に自動バックアップを行い、機体がアーム状態の場合は拒否し、書き込み後に読み戻して確認します。

iNAV MCP セッション — Claude がフライトコントローラーを見つけ、USB 経由でステータスを読み取る様子

_{USB 経由で実機の iNAV 6.1.0 フライトコントローラーに接続して記録しました。}

⚠️ 安全上の注意： モーターをテストする前に、必ず機体からプロペラを取り外してください。このツールが FC を MSP-RX モードに切り替えたり、機体をアームしたりすることはありません。

必要条件

Python 3.10+
USB 接続された iNAV フライトコントローラー（iNAV 8.x/9.x を対象に開発）
FC が認識されるシリアルポート（例：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]"

フライトコントローラーなしで試す

プロジェクトが動作することを確認するために、ハードウェアは必要ありません。テストスイートは完全にオフラインで実行されます（FC は不要です）。

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

テストはすべて 186 件成功するはずです。ただし、サーバーを実際に使用するには、iNAV ファームウェアを書き込んだフライトコントローラー（iNAV 8.x/9.x を対象に開発）を USB 接続する必要があります。FC がないと、接続ツールの通信相手がいません。

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 の FC に接続して、アームできない理由を教えて。」

「DSHOT600 で 4S フライングウィングをセットアップして、適用する前にコマンドを見せて。」

ツール（35）

接続と識別

ツール	説明
`list_serial_ports()`	利用可能なシリアルポートを一覧表示します。
`find_fc(baud=115200, probe_all=False)`	MSP の識別情報を照会して FC が接続されたポートを自動検出します。ポートを推測する必要はありません。
`connect(port, baud=115200)`	FC への接続を開き、ボードの識別情報を返します。
`disconnect()`	接続を閉じます。
`board_info()`	FC のバリアント、ファームウェアのバージョン、ターゲット、API バージョン、センサーを取得します。

ハードウェアのセットアップ

ツール	機能
`define_aircraft(name, wing_type, esc_protocol, cells, …)`	オフラインのプランナーです。プロファイルを保存し、CLI 設定プランを生成します。
`get_aircraft_profile()`	現在宣言されているプロファイルとプランを取得します。
`apply_aircraft_setup(confirm=False)`	プランを適用します（条件付き：アームされていないこと、自動バックアップ、読み戻しによる検証）。iNAV では、適用時に必ず保存と再起動が行われます。
`check_config()`	`diff all` と、宣言されたプロファイルに対する静的チェック、および ARM チェックを実行します。

フライトモードとスイッチ

ツール	機能
`suggest_mode_layout(skill_level, num_switches, has_gps=False)`	固定翼向けのスイッチ／モード構成を推奨します（オフライン）。
`set_flight_mode(mode_name, aux_channel, range_low, range_high, confirm=False)`	1つのモードを1つの AUX 範囲に割り当てます。
`assign_switch(switch_channel, switch_positions, mode_per_position, confirm=False)`	2／3／6ポジションスイッチ全体を1回の呼び出しで割り当てます。
`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)`	モーターを1基、短時間だけ回転させます。厳格な条件付きです：`props_removed=True` と `confirm=True` が必要で、アーム中は実行できず、必ず自動停止します。（`test_servo` はありません。iNAV にはサーボをリアルタイムでオーバーライドする機能がないため、送信機のスティックと `read_rc_channels()` で舵面を確認してください。）
`calibrate_accelerometer(confirm=False)`	加速度センサーのゼロレベルを調整します（ボードを水平にして静止させます）。「水平ではない」ことによるアーミング阻止の大半を解消します。
`calibrate_magnetometer(confirm=False)`	コンパスをキャリブレーションします（機体を約30秒間回転させます）。

ナビゲーションとチューニング

ツール	機能
`read_gps()`	GPS のリアルタイムの測位状態／衛星数／位置と、ナビゲーション準備状況の評価を取得します（読み取り専用）。
`configure_gps(provider="UBLOX", sbas=None, confirm=False)`	GPS 機能を有効にし、プロバイダー／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)`	1つの軸について、固定翼機の 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 信号喪失時の手順／スロットルを設定します（アトミック書き込み。FC が手順トークンを検証します）。
`cli(command, confirm_for_writes=False, props_removed=False)`	CLI を直接実行するための手段です（コマンドは1つ、再起動は1回）。書き込みには `confirm_for_writes` が必要です。モーターのリアルタイムテストには `props_removed=True` が必要で、設定として保存されることはありません。
`cli_batch(commands, confirm_for_writes=False)`	多数の CLI コマンドを1つのセッションで実行し、再起動は1回だけ行います。読み取り専用のバッチは保存せずに終了します。書き込みバッチではバックアップを作成して1回だけ保存し、コマンドが1つでも拒否された場合はロールバックします。モーター／`save`／`exit` コマンドは拒否されます。
`save_and_reboot(confirm=False)`	EEPROM に `save` して再起動します（接続は古い状態になります）。

リソース

inav://modes-reference — 固定翼機に関連する iNAV モードの用語集です。
inav://current-profile — 宣言済みの機体プロファイルと生成されたプランです。
inav://last-backup — 最新の diff all バックアップです。

安全モデル

プロペラ取り外しゲート — test_motor() と、cli(...) 経由で実行するすべてのライブ motor コマンドには props_removed=True が必要です（汎用の書き込み確認では回避できません）。FC がアーム状態の場合は拒否され、保存されることもありません。test_motor() はスロットルと継続時間に上限を設け、モーターを必ず停止状態に戻します。
アーム状態ガード — FC がアーム状態を報告している場合、すべての書き込み（モーターテスト／キャリブレーションを含む）を拒否します。
自動バックアップ — 書き込みの前に毎回バックアップを作成し、バックアップのパスを返します。
デフォルトでドライラン — 書き込みでは正確なコマンドが返されます。適用するには confirm=True を指定します。
読み戻し検証 — 適用後に設定を再読み込みし、不一致があれば報告します。
save = 再起動 — save_and_reboot は警告を表示し、接続が古くなったことを示します。
受信機モードは変更しません — FC が MSP-RX に切り替えられることはありません。

再起動モデル — バッチ処理が重要な理由

iNAV では、CLI を終了すると必ず FC が再起動します。save（EEPROM への保存）と exit（変更の破棄）のどちらでも再起動が発生し、その後 USB VCP が再列挙され、再接続します（約 6～8 秒。reboot_seconds として表示されます）。つまり、読み取り専用の操作（get、diff、dump、version）も含め、CLI のラウンドトリップごとに 1 回再起動します。再起動せずに 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 セッションを 1 回だけ開始し、バックアップ → すべてのコマンドを適用 → 保存 → 再起動を 1 回行います。複数の設定でも再起動は 1 回です。
個別の実行には cli_batch() を使います。 cli() をループ内で呼び出す（コマンドごとに再起動し、基板が DFU モードになるおそれのある間隔で再起動する）代わりに、リストを cli_batch() に渡します。セッションは 1 回、再起動も 1 回です。読み取り専用のバッチでは保存せずに exit します。書き込みバッチでは事前にバックアップを作成して 1 回だけ save し、コマンドが 1 つでも拒否された場合はロールバックします。
再接続は堅牢です。 再起動後、再接続では短い安定待機を挟んでから、間隔を延ばしながらポーリングします。元の COM ポートが戻らない場合は、再列挙されたポートをスキャンします。また、基板が DFU／ブートローダーモード で戻ってきた場合は、その旨を伝えて、停止したままにせず電源の入れ直し（USB の抜き差し）を案内します。

動作の仕組み

単一のシリアルハンドルを MSP モードと CLI モードで共有し（connection.py）、mode 状態機械で追跡します。1 つのポートでハンドルを 2 つ使用することはありません。
書き込みには 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)`	複数ポジションスイッチの各位置を、1 回の呼び出しでフライトモードに割り当てます。
`backup_config(label=None)`	現在の FC 設定を、タイムスタンプ付きのバックアップファイルに保存します。
`board_info()`	MSP 経由でフライトコントローラーの識別情報を読み取ります。
`calibrate_accelerometer(confirm=False)`	加速度計を（水平状態で）キャリブレーションします。「not level」や「accel not」の問題のほとんどを解決します。
`calibrate_magnetometer(confirm=False)`	コンパス（磁力計）をキャリブレーションします。コンパスを搭載している場合にのみ役立ちます。
`check_config()`	FC の実際の設定と、宣言された航空機プロファイルを比較します。
`check_failsafe()`	フェイルセーフ設定（RC 信号が途切れた場合の動作）を読み取り、説明します。
`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 コマンドを 1 回の CLI セッションで実行します。バッチ全体で再起動は 1 回だけです。
`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()`	CLI 経由で固定翼の PID ゲイン、レート、主要なフィルターカットオフ値を読み取ります。
`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)`	CLI の「aux」で読み取り・変更・書き込みを行い、フライトモードを 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 ゲインを、1 つの軸に対して設定します（アトミックな 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)`	ベンチテスト用に、モーターを 1 基だけ短時間回転させます（回転方向／配線／応答を確認します）。
`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）をインポートしません。そのため、寛容なライセンスを維持できます。

Markdown 対応

ログインしてコメント

基本情報

作者: starlordz12
言語: python
バージョン: 1.0.0
トランスポート: stdio
掲載日: 2026年10月26日
最終更新: 2 日前
公式 Registry: io.github.starlordz12/inav-mcp

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。