ardupilot-mcp

ardupilot-mcp

Türkçe · 英語

ArduPilot のフライトログを診断する MCP サーバーです。Claude Desktop、Cursor、VS Code などの AI クライアントに追加して、.bin または .tlog ファイルを渡すと、クライアントが振動、バッテリー残量の低下、GPS の喪失、モーターの故障、設定ミスなど、飛行中に起きたことを分かりやすく説明します。

検出結果は決定論的なチェックによって生成されます。各しきい値の出典は docs/SOURCES.md に記載されており、モデルは検出結果を説明するだけです。サーバーはローカルファイルのみを読み取り、ネットワークに接続せず、機体にコマンドを送信せず、パラメーターを書き込みません。

クイックスタート

Claude Desktop の場合：

1. uv をインストールします。
2. Claude Desktop で Settings → Developer → Edit Config を開き、次を追加します。

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

3. Claude Desktop を完全に終了してから、再起動します。
4. 次のように尋ねます：「C:\loglar\00000042.BIN のログを分析して、なぜ墜落したのか教えてください」

Claude Code なら、次の1行で設定できます：claude mcp add ardupilot-mcp -- uvx ardupilot-mcp。Cursor、VS Code、Windsurf、Cline、Zed、LM Studio などのクライアント設定、トラブルシューティング、クライアントを使わない試用方法については、docs/clients.md を参照してください。

どのログを使う？

• .bin はフライトコントローラー自体が記録するログで、最も詳細な診断ができます。SD カードの APM/LOGS/ フォルダーにあります。Mission Planner の DataFlash Logs → Download DataFlash Log Via Mavlink からもダウンロードできます。
• .tlog は地上局が記録するテレメトリーです。1秒あたり数サンプルで、主要センサーのみを記録するため、診断の精度は下がります。無線の切断を機体の故障と誤認する可能性があるチェックは、このファイルでは実行されません。

例

python examples/analyze.py demo.bin の出力の一部です。クライアントは同じ検出結果を、あなたの言語で説明します。

First anomaly while armed: Elevated VibeZ vibration @ 9s.
6 critical, 2 warning, 3 info finding(s).
[CRITICAL] vibration @ 9s: Elevated VibeZ vibration
           VibeZ vibration peaks at 72 m/s^2 (>60); 20% of samples exceed 60 m/s^2.
[CRITICAL] attitude  @ 20s: Attitude tracking failure (roll)
           Roll failed to track the demand for 3.0 s, error up to 35 deg (sustained >25 deg).
[CRITICAL] power     @ 25s: Battery reached critical voltage
           Pack voltage fell to 13.32 V, at or below the critical-voltage level (13.50 V, configured BATT_*_VOLT failsafe).

ツール

すべてのツールは読み取り専用です。

ツール	説明
analyze_log	すべてのチェックを実行し、重要度順に並べた検出結果を、ArduPilot の公式ドキュメントへのリンクとともに返します。
incident_timeline	最初の異常と墜落の時点を特定し、イベントを時系列に並べます。因果関係は主張しません。
forum_report	discuss.ardupilot.org に貼り付ける Markdown の返信を作成します。GPS 位置情報は含みません。
compare_logs	2つのフライト間で変化したパラメーター、ファームウェア、メトリクスを並べて表示します。
log_summary	機体、ファームウェア、飛行時間、フライトモード、ログの整合性を表示します。
vehicle_profile	フレーム、モーター数、バッテリー、ホバー時のスロットル、出力マージンを表示します。
list_events	ERR、MODE、EV、MSG レコードのタイムラインを表示します。
query_timeseries	検出結果の根拠となる生データ系列を表示します。複数のセンサーがある場合は、インスタンスを選択できます。
get_params	ログ内のパラメーターと、そのファームウェアバージョンで文書化されている範囲、単位、値を表示します。
load_param_file	エクスポートされた .param ファイルを読み込みます。
recommend_tuning	高調波ノッチ、PID、自動チューニングの推奨を提示します。変更は適用しません。
list_checks	登録済みチェックの一覧を表示します。

ツールの引数と18種類すべてのチェックについては、docs/reference.md を参照してください。このファイルは scripts/gen_docs.py がコードから生成し、CI が最新の状態かどうかを確認します。

仕組み

パーサーはログを列指向のFlightLogモデルに変換します。登録済みのチェックはこのモデルを読み取ります。データがログにないチェックはスキップされ、機体タイプに適合しないチェックは実行されません。同じ事象のERRレコード、フェイルセーフモードの変更、ファームウェアメッセージは、1つの検出結果にまとめられます。衝突後に始まる検出結果はリストの末尾に移動し、レポートの先頭には衝突前に発生した最初の異常が残ります。

4.xファームウェアは、各IMU、GPS、コンパス、バッテリー、EKFコアを1つのメッセージ名で記録します。チェックではそれぞれを個別に評価します。4.1より前のログで別々の名前で記録されているセンサーも、同じ構造に変換されます。

サーバーはMCP Python SDK 2で動作します。2026-07-28のプロトコルバージョンと、現在ほとんどのデスクトップクライアントが使用している旧式のハンドシェイク（2024-11-05から2025-11-25まで）の両方に対応しています。

精度と制限事項

エンジンは、フォーラムに投稿された実際の事故ログ49件を使って測定されています。各ログの原因は、そのログを調査した開発者または経験豊富なユーザーが記録しています。最新のスコアと手法についてはbench/README.mdをご覧ください。

• コンパスの方位誤差による円形の流され（トイレボウル現象）は、まだ検出されません。
• フォーマット定義が破損したログでは、部分的な結果ではなく、明示的なエラーが返されます。
• .tlogファイルには、ERRレコード、バッチサンプラー、高速IMU、モード変更の理由が含まれていません。
• 検出結果は意思決定を支援するものであり、飛行可能性の判断を行うものではありません。

その他のツール

UAV Log ViewerとMission PlannerのAuto Analysisはデータを表示しますが、解釈はユーザーに委ねます。ardupilot-mcpは解釈を行い、追加の質問にも回答します。信号をグラフで確認したり、飛行を3Dで追跡したりするには、UAV Log Viewerの方が適しています。

貢献

CONTRIBUTING.mdでは、開発環境のセットアップ、新しいチェックの追加、PRの手順について説明しています。AIアシスタントが従うルールはAGENTS.mdに記載されています。セキュリティ上の脆弱性は、SECURITY.mdに記載された手順で報告してください。変更内容はCHANGELOG.mdに記載されています。

ライセンス

GNU AGPL-3.0。コードを変更してネットワーク経由のサービスとして提供する場合、変更したソースコードをそのサービスのユーザーに公開する必要があります。AGPLの条件が用途に合わない場合は、[email protected]まで商用ライセンスについてお問い合わせください。PyPIで公開された0.1.3以前のパッケージはMITライセンスであり、今後もそのままです。この変更以降のソースコードと今後のリリースは、AGPL-3.0ライセンスです。

ardupilot_mcp/data/params/以下のデータは、ArduPilotのGPLv3ライセンスのパラメーター定義（apm.pdef.xml）から抽出された情報で構成されています。具体的には、範囲、単位、値コード、ビットマスクのビットが含まれます。説明文は複製していません。