mavlink-mcp

mavlink-mcp ist eine anbieterneutrale UAV-Funktionsschicht + Model Context Protocol-Server, der auf offenen Standards basiert. Es verbindet KI-Agenten (Claude Desktop, Cursor, VS Code und jeden anderen MCP-Client) mit Drohnen, die MAVLink sprechen – PX4 SITL, ArduPilot SITL und Pixhawk-Klasse-Autopiloten – über MAVSDK (BSD-3-Clause). Anstatt Protokollnachrichten zu kapseln, stellt es 8 Flugfähigkeiten (Telemetrie, Flugmodus, Bewaffnen/Entwaffnen, Starten, Landen, Gehe-zu, Mission, Rückkehr-zum-Start) hinter einer sauberen API mit standardmäßig aktivierten Sicherheitsvorkehrungen bereit.

Es ist das Schwesterprojekt von rosbridge-mcp (KI-Agenten ↔ ROS 2 Roboter) und teilt dessen Philosophie: nur offene Protokolle, Readonly-by-default-Sicherheitsvorkehrungen, Simulation zuerst, keine Telemetrie, MIT-Lizenz.

Hinweis zum Namen: „mavlink-mcp“ ist ein vorläufiger Arbeitstitel. „MAVLink“ ist eine Marke der Dronecode Foundation; der Projektname kann nach Prüfung ihrer Markenpolitik vor einer öffentlichen Veröffentlichung angepasst werden.

Sicherheitshinweis: Dieses Projekt ist für Simulation und Forschung konzipiert. Der Einsatz mit echten Fluggeräten erfolgt vollständig auf eigenes Risiko und in eigener Verantwortung, einschließlich der Einhaltung Ihrer lokalen Luftfahrtgesetze (Registrierung, Fluggenehmigungen, Pilotenlizenz). Siehe SECURITY.md.

Warum eine Funktionsschicht und nicht ein weiteres SDK?

• Für KI-Agenten sind Fähigkeiten besser als 400 SDK-Funktionen. Ein Agent fragt get_capabilities („Was kann diese Drohne?“), erhält ein kleines Vokabular physikalischer Aktionen und plant damit – kein MAVLink-Wissen auf der Modellseite erforderlich.

• Von Natur aus anbieterneutral. Fähigkeiten werden in physikalischen Größen (Grad, Meter, Volt) aus offenen Spezifikationen definiert – nicht aus einer proprietären SDK-Oberfläche kopiert. Der MAVSDK-Adapter ist eine Implementierung; ein zukünftiger ROS 2-Adapter (der rosbridge-mcp wiederverwendet) implementiert dieselbe Schnittstelle.

• Sicherheitsvorkehrungen sind Teil der API, kein nachträglicher Einfall. Der Readonly-Modus ist die Voreinstellung, Bewaffnen und Starten erfordern eine explizite, vom Bediener bestätigte Zustimmung, und jeder befohlene Standort wird vor Erreichen des Autopiloten gegen eine Höhenbegrenzung und einen weichen Geofence geprüft.

Related MCP server: ArduPilot MCP Server Sandbox

Architektur

+--------------------+  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).

Die Funktionsschicht (Drone) besitzt die gesamte Richtlinie – Readonly, Bestätigung, Höhe, Geofence. Der Adapter (MavsdkAdapter) übersetzt nur genehmigte Operationen in MAVLink; er ist das einzige Modul, das mavsdk importiert. Neue Backends implementieren dasselbe DroneAdapter-Interface und erben beide Oberflächen (MCP-Tools + Python-Bibliothek) sowie jede Sicherheitsvorkehrung kostenlos.

Kurzanleitung (60 Sekunden)

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

Starten Sie einen PX4 SITL (siehe docs/simulator-quickstart.md – ein Docker-Befehl), dann fügen Sie Folgendes zu Ihrer MCP-Client-Konfiguration hinzu:

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

Fragen Sie dann Ihren Agenten: „Was kann diese Drohne und wo ist sie gerade?“

Wenn Sie bereit zum Fliegen sind (im Simulator!), setzen Sie MAVLINK_MCP_READONLY auf "false".

Fähigkeiten & Werkzeuge

12 Werkzeuge, die 8 Fähigkeiten abdecken. Alle Werkzeuge geben JSON zurück; Fehler werden als {"error": "...", "guardrail": true} gemeldet, anstatt eine Ausnahme auszulösen, damit der Agent sie lesen und darauf reagieren kann.

Beispielunterhaltung

Sie: Überprüfen Sie die Drohne und, wenn sie gesund ist, machen Sie eine kurze Patrouille auf 20 m.

Agent: (ruft get_capabilities auf – sieht, dass Readonly aus ist, Geofence 200 m; ruft get_telemetry auf – GPS FIX_3D, 10 Satelliten, Batterie 100%) Die Drohne ist gesund. Ich benötige Ihre Zustimmung zum Bewaffnen und Starten – bestätigen Sie?

Sie: Bestätigt, machen Sie weiter.

Agent: (ruft arm(confirm=true), takeoff(altitude_m=20, confirm=true) auf, dann fly_mission mit 3 Wegpunkten innerhalb des Geofence, überwacht get_telemetry, beendet mit return_to_launch) Patrouille abgeschlossen – die Drohne ist am Startpunkt zurück und entwaffnet.

Konfiguration

Sicherheit

Einem Sprachmodell die Steuerung eines Luftfahrzeugs zu überlassen, ist ein echtes Risiko, daher sind die Sicherheitsvorkehrungen strenger als bei einem typischen SDK:

1. Readonly standardmäßig. Im Gegensatz zu den meisten Werkzeugen müssen Sie sich explizit für den Flug mit MAVLINK_MCP_READONLY=false entscheiden. Im Readonly-Modus funktionieren alle Telemetrie-Werkzeuge; jedes verändernde Werkzeug wird mit einer klaren Erklärung abgelehnt.

2. Zweistufige Bestätigung für die gefährlichen Übergänge. arm und takeoff erfordern confirm=true, und die Werkzeugbeschreibungen weisen den Agenten an, zuerst eine menschliche Zustimmung einzuholen – ein Agent kann nicht legitimerweise in einem einzigen autonomen Schritt starten.

3. Weicher Geofence + Höhenbegrenzung. Jeder befohlene Standort (goto und jeder Missionswegpunkt) wird gegen MAVLINK_MCP_GEOFENCE_RADIUS_M um die Heimat und MAVLINK_MCP_MAX_ALTITUDE_M validiert, bevor etwas an den Autopiloten gesendet wird.

4. Sicherheitsaktionen bleiben reibungslos. land, hold und return_to_launch erfordern niemals eine Bestätigung – Deeskalation muss immer einfach sein.

Diese Prüfungen sind Richtlinien innerhalb dieses Prozesses – kein Ersatz für die eigenen Ausfallsicherungen des Autopiloten, einen echten, in PX4/ArduPilot konfigurierten Geofence, Netzwerkisolation oder einen Menschen mit einem RC-Sender. Lesen Sie SECURITY.md, bevor Sie echte Hardware in Betracht ziehen, und behandeln Sie reale Flüge als registrierungs-/genehmigungspflichtig gemäß Ihrem lokalen Luftfahrtrecht (z. B. Vietnams UAV-Dekret 288/2025 erfordert Registrierung und Fluggenehmigungen).

Python-Bibliothek

Dieselbe Funktionsschicht kann für Skripte und Notebooks importiert werden – siehe examples/patrol_sitl.py für einen vollständigen Start → Wegpunkt → Lande-Durchlauf gegen SITL:

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)

Datenschutz & Rechtliches

Keine Telemetrie, keine Datenerfassung. Die einzige Netzwerkverbindung, die dieses Paket öffnet, ist der von Ihnen konfigurierte MAVLink-Endpunkt (MAVLINK_MCP_URL). Vom Fahrzeug zurückgegebene Daten gehen ausschließlich an Ihren MCP-Client.

Lizenzkonformität. Der Kern hängt bewusst von MAVSDK-Python (BSD-3-Clause) und nicht von pymavlink (LGPL-3) ab, wodurch der Abhängigkeitsbaum unter der MIT-Lizenz dieses Projekts permissiv bleibt. Direkte Abhängigkeiten: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). Der gesamte Code in diesem Repository ist originäre Arbeit, die aus öffentlichen, offenen Spezifikationen (MAVLink-Protokolldokumentation, MAVSDK-Dokumentation) geschrieben wurde – keine proprietären SDKs, kein Reverse Engineering, keine Anbieter-EULAs akzeptiert.

FAQ

Brauche ich eine Drohne? Nein. MVP1 ist simulationsorientiert: Alles funktioniert gegen PX4 SITL (ein Docker-Befehl) und ist so konzipiert, dass es auch gegen ArduPilot SITL funktioniert. Siehe docs/simulator-quickstart.md.

Funktioniert es mit ArduPilot? Die Funktionsschicht zielt sowohl auf PX4 als auch auf ArduPilot über MAVSDK ab. PX4 SITL ist das primär getestete Ziel in MVP1; Hinweise zur Kompatibilität mit ArduPilot SITL finden Sie in der Kurzanleitung, und die Validierung in CI ist ein Roadmap-Punkt.

Warum nicht einfach MAVSDK direkt verwenden? Wenn Sie Python von Hand schreiben, tun Sie das! mavlink-mcp fügt die Ebene hinzu, die MAVSDK nicht hat: eine MCP-Werkzeugoberfläche für KI-Agenten, ein Fähigkeitsmodell mit Laufzeiterkennung und Produktionssicherheitsvorkehrungen (Readonly, Bestätigung, Geofence), die oberhalb des Protokolls durchgesetzt werden.

Der Agent sagt, es wurde kein Fahrzeug gefunden. Überprüfen Sie, ob der SITL läuft und MAVLink an den Endpunkt in MAVLINK_MCP_URL sendet (PX4 SITL sendet standardmäßig an UDP 14540). Die Kurzanleitung enthält eine Fehlerbehebungstabelle.

Werden meine Daten irgendwohin gesendet? Nur an Ihren MCP-Client, der sie an das von Ihnen verwendete LLM weiterleitet – behandeln Sie Positionsdaten entsprechend.

Roadmap

Gestaffelter Plan in ROADMAP.md: MVP1 (dies – Funktionsschicht + MCP-Server auf SITL), MVP2 (echte Pixhawk-Klasse-Hardware, ROS 2-Adapter unter Wiederverwendung von rosbridge-mcp, Plugin-/Konformitätssystem), MVP3 (Community-Adapter, Mehrfachfahrzeuge, Open-Core-Dienste).

Mitwirken

Beiträge sind willkommen – siehe CONTRIBUTING.md. Bitte signieren Sie Ihre Commits (DCO). Beachten Sie die Regel für saubere Beiträge: PRs müssen ausschließlich auf öffentlichen Spezifikationen und Dokumentationen basieren.

Lizenz

MIT – siehe LICENSE. Die Abhängigkeitslizenzen sind permissiv und kompatibel: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). Keine GPL/LGPL/AGPL-Abhängigkeiten im Kern.

Tóm tắt tiếng Việt

mavlink-mcp là lớp capability trung lập (vendor-neutral) cho UAV kèm MCP server, xây hoàn toàn trên chuẩn mở: kết nối AI agent (Claude Desktop, Cursor, VS Code...) với drone nói MAVLink (PX4/ArduPilot) qua thư viện MAVSDK (BSD-3). Đây là dự án chị em của rosbridge-mcp.

• 8 Fähigkeiten: Telemetrie (Position/Lage/Akku/GPS), flight mode, arm/disarm, takeoff, land, goto, mission, return-to-launch — 12 Tool MCP.

• Standardsicherheit: Readonly-Modus standardmäßig aktiviert (MAVLINK_MCP_READONLY standardmäßig true); Arm und Takeoff erfordern confirm=true nach Zustimmung des Bedieners; weicher Geofence + konfigurierbare Höhenbegrenzung.

• Simulation-first: Läuft mit PX4 SITL (1 Docker-Befehl) — siehe docs/simulator-quickstart.md. Das Projekt ist für Simulation/Forschung gedacht; echte Flüge liegen in Ihrer eigenen Verantwortung, einschließlich Geräteregistrierung und Fluggenehmigung gemäß Luật Phòng không nhân dân 49/2024 und Nghị định 288/2025.

• Der Name "mavlink-mcp" ist vorläufig — wird vor der Veröffentlichung die Markenrichtlinie von Dronecode überprüft.