mavlink-mcp

mavlink-mcp は、オープンスタンダード上に構築された ベンダーニュートラルなUAV機能レイヤー + Model Context Protocol サーバーです。これは、AIエージェント（Claude Desktop、Cursor、VS Code、その他のMCPクライアント）を、MAVSDK（BSD-3-Clause）を通じて MAVLink を話すドローン（PX4 SITL、ArduPilot SITL、Pixhawkクラスのオートパイロット）に接続します。プロトコルメッセージをラップする代わりに、1つのクリーンなAPIの背後に 8つの飛行機能（テレメトリー、フライトモード、アーム/ディスアーム、離陸、着陸、移動、ミッション、発進地点への帰還）を公開し、デフォルトで安全ガードレールが有効になっています。

これは rosbridge-mcp（AIエージェント ↔ ROS 2 ロボット）の姉妹プロジェクトであり、その哲学を共有しています：オープンプロトコルのみ、デフォルトで読み取り専用のガードレール、シミュレーション優先、ゼロテレメトリー、MITライセンス。

名称に関する注意: 「mavlink-mcp」は暫定的な作業名です。「MAVLink」はDronecode Foundationの商標です。プロジェクト名は、公開リリース前に商標ポリシーのレビューを経て調整される可能性があります。

安全に関する免責事項: このプロジェクトはシミュレーションおよび研究用に構築されています。実際の航空機を飛行させる場合は、ご自身の責任とリスクで行ってください。また、現地の航空法（登録、飛行許可、パイロットライセンス）の遵守も含まれます。SECURITY.md を参照してください。

なぜ機能レイヤーであって、別のSDKではないのか？

• AIエージェントにとって、機能は400のSDK関数よりも優れている。 エージェントは get_capabilities（「このドローンは何ができるか？」）を要求し、物理的なアクションの小さな語彙を取得し、それを基に計画を立てます。モデル側でMAVLinkの知識は不要です。

• 設計上、ベンダーニュートラル。 機能は、オープンな仕様から物理量（度、メートル、ボルト）で定義されており、プロプライエタリなSDKの表面からコピーされたものではありません。MAVSDKアダプターは1つの実装であり、将来のROS 2アダプター（rosbridge-mcpを再利用）は同じインターフェースを実装します。

• ガードレールはAPIの一部であり、後付けではない。 読み取り専用モードがデフォルトであり、アームと離陸には明示的なオペレーター承認の確認が必要であり、コマンドされたすべての位置は、オートパイロットに到達する前に、高度制限とソフトジオフェンスに対してチェックされます。

Related MCP server: ArduPilot MCP Server Sandbox

アーキテクチャ

+--------------------+  stdio (MCP)  +----------------------------------+  MAVLink (UDP)  +------------------+
|  AI client         | <-----------> | mavlink-mcp                      | <-------------> | PX4 / ArduPilot  |
|  (Claude, Cursor,  |               |  MCP server                      |     via         |  SITL or real FC |
|   VS Code, ...)    |               |   └─ capability layer + policy   |    MAVSDK       |  (Pixhawk-class) |
+--------------------+               |       └─ MAVSDK adapter          |    (BSD-3)      +------------------+
                                     +----------------------------------+
Python scripts use the same capability layer directly (mavlink_mcp.Drone).

機能レイヤー（Drone）は、すべてのポリシー（読み取り専用、確認、高度、ジオフェンス）を所有します。アダプター（MavsdkAdapter）は、承認された操作のみをMAVLinkに変換します。これは mavsdk をインポートする唯一のモジュールです。新しいバックエンドは同じ DroneAdapter インターフェースを実装し、両方の表面（MCPツール + Pythonライブラリ）とすべてのガードレールを無料で継承します。

クイックスタート（60秒）

pip install git+https://github.com/hieutachi/mavlink-mcp.git

PX4 SITLを起動し（docs/simulator-quickstart.md を参照 — Dockerコマンド1つ）、次にMCPクライアント設定に追加します：

{
  "mcpServers": {
    "mavlink": {
      "command": "mavlink-mcp",
      "env": { "MAVLINK_MCP_READONLY": "true" }
    }
  }
}

次にエージェントに尋ねてみてください：「このドローンは何ができて、今どこにいるの？」

飛行する準備ができたら（シミュレーター内で！）、MAVLINK_MCP_READONLY を "false" に設定します。

機能とツール

8つの機能をカバーする12のツール。すべてのツールはJSONを返します。エラーは、発生する代わりに {"error": "...", "guardrail": true} として返されるため、エージェントはそれを読み取って対応できます。

会話例

あなた: ドローンをチェックして、問題がなければ20mで短いパトロールをしてください。

エージェント: （get_capabilities を呼び出す — 読み取り専用がオフ、ジオフェンス200mを確認。get_telemetry を呼び出す — GPS FIX_3D、10衛星、バッテリー100%） ドローンは正常です。アームと離陸の承認が必要です。確認しますか？

あなた: 確認しました、進めてください。

エージェント: （arm(confirm=true)、takeoff(altitude_m=20, confirm=true)、次にジオフェンス内の3つのウェイポイントで fly_mission を呼び出し、get_telemetry を監視し、最後に return_to_launch を実行） パトロール完了 — ドローンは発進地点に戻り、ディスアームされました。

設定

安全性

言語モデルに航空機を命令させることは実際のリスクであるため、ガードレールは通常のSDKよりも厳格です。

1. デフォルトで読み取り専用。 ほとんどのツールとは異なり、飛行には MAVLINK_MCP_READONLY=false で明示的にオプトインする必要があります。読み取り専用モードでは、すべてのテレメトリーツールが機能します。すべての変更を伴うツールは、明確な説明とともに拒否されます。

2. 危険な遷移には2段階の確認。 arm と takeoff には confirm=true が必要であり、ツールの説明はエージェントにまず人間の承認を得るように指示します。エージェントが単一の自律ステップで正当に離陸することはできません。

3. ソフトジオフェンス + 高度制限。 コマンドされたすべての位置（移動および各ミッションウェイポイント）は、オートパイロットに送信される前に、ホームを中心とした MAVLINK_MCP_GEOFENCE_RADIUS_M および MAVLINK_MCP_MAX_ALTITUDE_M に対して検証されます。

4. 安全アクションは摩擦なし。 land、hold、return_to_launch は確認を必要としません。エスカレーション解除は常に低コストである必要があります。

これらのチェックはこのプロセス内のポリシーであり、オートパイロット自身のフェイルセーフ、PX4/ArduPilotで設定された実際のジオフェンス、ネットワーク分離、またはRC送信機を持つ人間の代わりにはなりません。実際のハードウェアを検討する前に SECURITY.md を読み、実際の飛行には現地の航空法（例：ベトナムの無人航空機に関する政令288/2025では登録と飛行許可が必要）に基づく登録/許可が必要であることを認識してください。

Pythonライブラリ

同じ機能レイヤーはスクリプトやノートブックからインポート可能です。完全な離陸→ウェイポイント→着陸のSITL実行例については examples/patrol_sitl.py を参照してください：

from mavlink_mcp import Drone, GuardrailConfig
from mavlink_mcp.adapters.mavsdk_adapter import MavsdkAdapter

drone = Drone(MavsdkAdapter(), guardrails=GuardrailConfig(readonly=False))
snapshot = await drone.get_telemetry()
await drone.arm(confirm=True)
await drone.takeoff(20.0, confirm=True)

プライバシーと法的注意事項

テレメトリーなし、データ収集なし。 このパッケージが開く唯一のネットワーク接続は、設定したMAVLinkエンドポイント（MAVLINK_MCP_URL）です。ツールによって返される車両データは、MCPクライアントにのみ送信されます。

ライセンス準拠。 コアは意図的に MAVSDK-Python (BSD-3-Clause) に依存しており、pymavlink (LGPL-3) には依存していません。これにより、このプロジェクトのMITライセンスの下で依存関係ツリーが寛容な状態に保たれています。直接の依存関係：mavsdk (BSD-3-Clause)、fastmcp (Apache-2.0)。このリポジトリ内のすべてのコードは、公開されたオープンな仕様（MAVLinkプロトコルドキュメント、MAVSDKドキュメント）から書かれたオリジナル作品です。プロプライエタリなSDK、リバースエンジニアリング、ベンダーEULAの受け入れはありません。

FAQ

ドローンは必要ですか？ いいえ。MVP1はシミュレーション優先です。すべてがPX4 SITL（Dockerコマンド1つ）に対して動作し、ArduPilot SITLに対しても動作するように設計されています。docs/simulator-quickstart.md を参照してください。

ArduPilotで動作しますか？ 機能レイヤーは、MAVSDKを通じてPX4とArduPilotの両方をターゲットにしています。PX4 SITLはMVP1の主要なテストターゲットです。ArduPilot SITLの互換性に関する注意事項はクイックスタートにあり、CIでの検証はロードマップ項目です。

なぜMAVSDKを直接使わないのですか？ Pythonを手動で書いている場合は、そうしてください！mavlink-mcpは、MAVSDKにはないレイヤーを追加します。AIエージェントのためのMCPツールサーフェス、実行時発見機能を備えた機能モデル、そしてプロトコル上で強制されるプロダクションガードレール（読み取り専用、確認、ジオフェース）です。

エージェントが車両が発見されなかったと言います。 SITLが実行されていて、MAVLINK_MCP_URL のエンドポイントにMAVLinkを送信しているか確認してください（PX4 SITLはデフォルトでUDP 14540に送信します）。クイックスタートにはトラブルシューティングテーブルがあります。

私のデータはどこかに送信されますか？ あなたのMCPクライアントにのみ送信され、クライアントは使用しているLLMに転送します。位置データはそれに応じて扱ってください。

ロードマップ

段階的な計画は ROADMAP.md にあります：MVP1（これ — SITL上の機能レイヤー + MCPサーバー）、MVP2（実際のPixhawkクラスハードウェア、rosbridge-mcpを再利用したROS 2アダプター、プラグイン/コンフォーマンスシステム）、MVP3（コミュニティアダプター、マルチビークル、オープンコアサービス）。

貢献

貢献は歓迎します — CONTRIBUTING.md を参照してください。コミットには署名オフ（DCO）をお願いします。クリーンコントリビューションルールに注意してください：PRは公開された仕様とドキュメントのみに基づく必要があります。

ライセンス

MIT — LICENSE を参照してください。依存関係のライセンスは寛容で互換性があります：mavsdk (BSD-3-Clause)、fastmcp (Apache-2.0)。コアにGPL/LGPL/AGPLの依存関係はありません。

ベトナム語要約（日本語訳）

mavlink-mcp は、UAV向けのベンダーニュートラルな機能レイヤーとMCPサーバーであり、すべてオープンスタンダード上に構築されています。MAVSDKライブラリ（BSD-3）を介して、AIエージェント（Claude Desktop、Cursor、VS Codeなど）とMAVLinkを話すドローン（PX4/ArduPilot）を接続します。これは rosbridge-mcp の姉妹プロジェクトです。

• 8 つの機能: テレメトリー（位置/姿勢/バッテリー/GPS）、フライトモード、アーム/ディスアーム、離陸、着陸、移動、ミッション、帰還 — 12 ツール MCP。

• デフォルトの安全性: 読み取り専用モードがデフォルトで有効（MAVLINK_MCP_READONLY はデフォルト true）；アームと離陸はオペレーターの同意後に confirm=true が必要；設定可能なソフトジオフェンス＋高度制限。

• シミュレーションファースト: PX4 SITL（Docker 1 コマンド）で実行 — docs/simulator-quickstart.md を参照。本プロジェクトはシミュレーション/研究用です。実際の飛行は、機器登録や人民防空法 49/2024 および政令 288/2025 に基づく飛行許可を含め、すべて自己責任で行ってください。

• 「mavlink-mcp」という名前は仮のものです — 公開前に Dronecode のトレードマークポリシーを確認します。