ardupilot-mavlink-mcp

ardupilot-mcp

AI エージェントが MAVLink 経由で ArduPilot の機体と通信できる MCP サーバーです。状態の読み取り、パラメーターの確認と変更、モードの切り替え、プリ・アーム失敗の読み取り、（条件付きで）アームまたはディスアームを行えます。まずは SITL での利用を想定しています。

インストール：pipx install ardupilot-mavlink-mcp

mcp-name: io.github.rmeadomavic/ardupilot-mavlink-mcp

警告

このツールは実機をアームして操作できます。 誤ったコマンドを送ると、プロペラが回転したり、機体が飛び去ったりする可能性があります。これを防ぐため、デフォルトでは作動機能は OFF です。--enable-actuation を指定した場合でも、--allow-real-vehicle も指定しない限り、実機（ループバック以外）への接続は拒否されます。SITL で開発してください。実機では、まずプロペラを外してベンチテストを行ってください。保証はありません。結果に対する責任は利用者自身にあります。

Why

LLM 向けの ArduPilot ツールの多くは、飛行後のログ分析を対象としています。このツールは稼働中の接続を操作します。稼働中の機体に接続し、状態やパラメーターを読み取り、モードを変更し、アームできない理由を着陸後ではなくその場で診断します。役立つのは、アームできない機体にエージェントを接続し、パラメーターとプリ・アーム時の STATUSTEXT を読み取らせて、GCS のメッセージログを目を凝らして確認する代わりに、その理由を教えてもらう使い方です。アームツールは実際の COMMAND_ACK 結果を報告し、拒否された場合はプリ・アームの理由を返します。強制アームは行いません。

Architecture

  agent (MCP client)                    ardupilot-mcp                     vehicle
 ┌──────────────────┐   JSON-RPC    ┌──────────────────────┐   MAVLink   ┌──────────┐
 │ Claude / etc.    │ ───stdio────▶ │  FastMCP tools       │ ──udp/tcp/  │ ArduPilot│
 │                  │ ◀───────────  │   │                  │   serial──▶ │  (SITL   │
 └──────────────────┘               │   ▼                  │ ◀────────── │  or FC)  │
                                    │  recv thread (1 reader)            └──────────┘
                                    │   ├─▶ message cache (latest/type)
                                    │   ├─▶ param store (request/collect)
                                    │   └─▶ COMMAND_ACK + STATUSTEXT
                                    └──────────────────────┘

MAVLink は非同期ストリームですが、MCP ツールは同期処理です。バックグラウンドスレッドが接続を所有する唯一の読み取りスレッドとなり、各メッセージタイプの最新メッセージをキャッシュし、PARAM_VALUE をパラメーターストアに振り分けます。ツール呼び出しはこれらのキャッシュを読み取ります（パラメーターはデータが届くまで待機します）。複数のスレッドが同時に recv_match を呼び出すことはありません。

What it does

• キャッシュから機体の状態を即座に読み取ります。 モード、アーム状態、GPS の測位状態と衛星数、バッテリー、姿勢、位置などを、接続をブロックせず、キャッシュ済みテレメトリーから提供します。
• アームできない原因を診断します。 ardupilot_arm は COMMAND_ACK の結果を返し、拒否された場合はプリ・アーム時の STATUSTEXT（例：AHRS: waiting for home、Accels inconsistent）を返します。安全チェックを尊重し、ARMING_CHECK=0 や強制アーム用のマジックナンバーは使いません。
• 実際のパラメーターテーブルからパラメーターを取得および設定します。設定はエコーバックされた PARAM_VALUE で確認します。
• 機体タイプ（Copter／Rover／Plane／Sub）ごとの名前に基づいてフライトモードを切り替えます。数値をハードコードしていません。

Quick start (SITL)

ArduPilot の SITL インスタンスが必要です。ardupilot のチェックアウトから：

# starts ArduCopter SITL; serves MAVLink on tcp:127.0.0.1:5760
sim_vehicle.py -v ArduCopter --console

サーバーをインストールして実行します（デフォルトでは読み取り専用です）。

pipx install ardupilot-mavlink-mcp          # or: uv tool install ardupilot-mavlink-mcp
ardupilot-mavlink-mcp --connect tcp:127.0.0.1:5760

SITL に対するパラメーターの書き込み、モード変更、アーム／ディスアームを許可するには、--enable-actuation を追加します。

Use with an MCP client

Claude Code：

claude mcp add ardupilot -- ardupilot-mavlink-mcp --connect tcp:127.0.0.1:5760

Claude Desktop／任意の mcpServers 設定：

{
  "mcpServers": {
    "ardupilot": {
      "command": "ardupilot-mavlink-mcp",
      "args": ["--connect", "tcp:127.0.0.1:5760"]
    }
  }
}

接続文字列には pymavlink の構文を使用します：tcp:127.0.0.1:5760（SITL）、udp:127.0.0.1:14550、serial:/dev/ttyACM0:115200。

ツール

ツール	種類	内容
ardupilot_connect	—	機体に接続します。デフォルトはローカルの SITL です。
ardupilot_vehicle_state	読み取り	モード、アーム状態、GPS、バッテリー、姿勢、位置をキャッシュから取得します。
ardupilot_recent_statustext	読み取り	最近の STATUSTEXT／prearm メッセージを取得します。アームに失敗した理由を確認するには、これを読み取ってください。
ardupilot_get_param	読み取り	1 つのパラメーターを読み取ります。
ardupilot_set_param	書き込み	パラメーターを設定し、エコーされた PARAM_VALUE で確認します。
ardupilot_list_params	読み取り	パラメーターを一覧表示します。glob（ATC_RAT_*）を任意で指定できます。
ardupilot_set_mode	書き込み	モード名を指定して、フライトモードの設定を要求します。
ardupilot_arm / ardupilot_disarm	書き込み	ゲートで保護されています。COMMAND_ACK で確認します。

書き込みツールはゲートで保護され、MCP の destructiveHint が設定されています。ライブテレメトリーはリソース ardupilot://telemetry としても公開されています。

対応機体

機体	ファームウェア	状態
ArduCopter	4.5	✓ SITL で検証済み
ArduRover（UGV/USV）	4.x	~ モードマップはありますが、未検証です
ArduPlane	4.x	~ モードマップはありますが、未検証です
ArduSub	4.x	~ 未テスト

MAVLink2 を前提としています。実機では飛行させていません。現時点では SITL のみです。

安全モデル

1. 操作ツールはデフォルトで無効です。--enable-actuation で有効にします。
2. 有効にしても、実際のリンク（シリアルまたはループバック以外のネットワーク）での操作は、--allow-real-vehicle も設定されていない限り拒否されます。
3. リンクの分類はフェイルセーフです。明確にループバックと判定できないものは、すべて実機として扱われます。
4. arm、disarm、set_param、set_mode はすべて、送信前にこのゲートを通過します。
5. アームには強制アームのオプションがなく、set_param は、両方の操作フラグが有効な場合でも、すべてのリンクで ARMING_CHECK への書き込みを（大文字と小文字を区別せずに）拒否します。

状態

動作する機能：ArduCopter SITL に対する読み取り、ゲートで保護されたパラメーター書き込み、モード変更、アーム／ディスアーム。ユニットテスト（Python 3.10–3.12）、実際の MAVLink ワイヤーチェック（scripts/wire_check.py）、ライブの ArduPilot SITL 実行（scripts/sitl_check.py）の 3 つの方法で検証済みです。

今後の目標：Rover／Plane／Sub の検証。ミッションのアップロード／ダウンロードとガイド飛行（離陸／goto／着陸）は保留中です。ミッションプロトコルは状態を持つハンドシェイクであり、ガイドコマンドには機体が飛び去るリスクがあるためです。ROADMAP.md を参照してください。

開発

git clone https://github.com/rmeadomavic/ardupilot-mcp && cd ardupilot-mcp
uv venv && uv pip install -e ".[dev]"
pytest -q
ruff check . && ruff format --check .
python scripts/wire_check.py            # offline real-wire check, no SITL needed

ライセンス

MIT — Kyle Adomavicius