mavlink-mcp

mavlink-mcp es una capa de capacidades para UAV neutral en cuanto al proveedor + un servidor Model Context Protocol construido sobre estándares abiertos. Conecta agentes de IA (Claude Desktop, Cursor, VS Code y cualquier otro cliente MCP) a drones que hablan MAVLink — PX4 SITL, ArduPilot SITL y pilotos automáticos clase Pixhawk — a través de MAVSDK (BSD-3-Clause). En lugar de envolver mensajes de protocolo, expone 8 capacidades de vuelo (telemetría, modo de vuelo, armado/desarmado, despegue, aterrizaje, ir a, misión, retorno al punto de lanzamiento) detrás de una API limpia con barreras de seguridad activadas por defecto.

Es el proyecto hermano de rosbridge-mcp (agentes de IA ↔ robots ROS 2) y comparte su filosofía: solo protocolos abiertos, barreras de solo lectura por defecto, simulación primero, cero telemetría, licencia MIT.

Nota sobre el nombre: "mavlink-mcp" es un nombre de trabajo provisional. "MAVLink" es una marca comercial de Dronecode Foundation; el nombre del proyecto podría ajustarse pendiente de una revisión de su política de marcas comerciales antes de cualquier lanzamiento público.

Descargo de responsabilidad de seguridad: este proyecto está construido para simulación e investigación. Volar aeronaves reales con él es completamente bajo su propio riesgo y responsabilidad, incluido el cumplimiento de su legislación de aviación local (registro, permisos de vuelo, licencias de piloto). Consulte SECURITY.md.

¿Por qué una capa de capacidades y no otro SDK?

• Para los agentes de IA, las capacidades superan a 400 funciones del SDK. Un agente pregunta get_capabilities ("¿qué puede hacer este dron?"), recibe un pequeño vocabulario de acciones físicas y planifica con él — no se necesita conocimiento de MAVLink en el lado del modelo.

• Neutral en cuanto al proveedor por construcción. Las capacidades se definen en cantidades físicas (grados, metros, voltios) a partir de especificaciones abiertas — no copiadas de ninguna superficie de SDK propietaria. El adaptador MAVSDK es una implementación; un futuro adaptador ROS 2 (reutilizando rosbridge-mcp) implementará la misma interfaz.

• Las barreras de seguridad son parte de la API, no un añadido. El modo de solo lectura es el predeterminado, el armado y el despegue requieren confirmación explícita aprobada por el operador, y cada ubicación comandada se verifica contra un techo de altitud y una geocerca suave — antes de que nada llegue al piloto automático.

Related MCP server: ArduPilot MCP Server Sandbox

Arquitectura

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

La capa de capacidades (Drone) posee toda la política — solo lectura, confirmación, altitud, geocerca. El adaptador (MavsdkAdapter) solo traduce operaciones aprobadas a MAVLink; es el único módulo que importa mavsdk. Los nuevos backends implementan la misma interfaz DroneAdapter y heredan ambas superficies (herramientas MCP + biblioteca Python) y todas las barreras de seguridad de forma gratuita.

Inicio rápido (60 segundos)

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

Inicie un PX4 SITL (consulte docs/simulator-quickstart.md — un comando Docker), luego agregue a la configuración de su cliente MCP:

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

Luego pregunte a su agente: "¿Qué puede hacer este dron y dónde está ahora?"

Cuando esté listo para volar (¡en el simulador!), establezca MAVLINK_MCP_READONLY en "false".

Capacidades y herramientas

12 herramientas que cubren 8 capacidades. Todas las herramientas devuelven JSON; los errores se devuelven como {"error": "...", "guardrail": true} en lugar de lanzar excepciones, para que el agente pueda leer y reaccionar.

Ejemplo de conversación

Tú: Revisa el dron y, si está en buen estado, haz una patrulla corta a 20 m.

Agente: (llama a get_capabilities — ve que el modo de solo lectura está desactivado, geocerca 200 m; llama a get_telemetry — GPS FIX_3D, 10 satélites, batería 100%) El dron está en buen estado. Necesito tu aprobación para armar y despegar — ¿confirmas?

Tú: Confirmado, adelante.

Agente: (llama a arm(confirm=true), takeoff(altitude_m=20, confirm=true), luego fly_mission con 3 puntos de ruta dentro de la geocerca, monitorea get_telemetry, finaliza con return_to_launch) Patrulla completada — el dron ha vuelto al punto de lanzamiento y está desarmado.

Configuración

Seguridad

Permitir que un modelo de lenguaje comande una aeronave es un riesgo real, por lo que las barreras de seguridad son más estrictas que en un SDK típico:

1. Solo lectura por defecto. A diferencia de la mayoría de las herramientas, debe optar explícitamente por el vuelo con MAVLINK_MCP_READONLY=false. En modo de solo lectura, todas las herramientas de telemetría funcionan; cada herramienta mutante es rechazada con una explicación clara.

2. Confirmación en dos pasos para las transiciones peligrosas. arm y takeoff requieren confirm=true, y las descripciones de las herramientas instruyen al agente a obtener la aprobación humana primero — un agente no puede despegar legítimamente en un solo paso autónomo.

3. Geocerca suave + techo de altitud. Cada ubicación comandada (ir a y cada punto de ruta de la misión) se valida contra MAVLINK_MCP_GEOFENCE_RADIUS_M alrededor del inicio y MAVLINK_MCP_MAX_ALTITUDE_M antes de que se envíe algo al piloto automático.

4. Las acciones de seguridad permanecen sin fricción. land, hold y return_to_launch nunca requieren confirmación — la desescalada siempre debe ser barata.

Estas comprobaciones son políticas dentro de este proceso — no un sustituto de las propias protecciones del piloto automático, una geocerca real configurada en PX4/ArduPilot, el aislamiento de la red o un humano con un transmisor de radio. Lea SECURITY.md antes de considerar hardware real, y trate los vuelos en el mundo real como si requirieran registro/permisos bajo su legislación de aviación local (por ejemplo, el Decreto de UAV 288/2025 de Vietnam requiere registro y permisos de vuelo).

Biblioteca Python

La misma capa de capacidades es importable para scripts y cuadernos — consulte examples/patrol_sitl.py para un recorrido completo de despegue → punto de ruta → aterrizaje contra 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)

Privacidad y legal

Sin telemetría, sin recopilación de datos. La única conexión de red que abre este paquete es el endpoint MAVLink que usted configura (MAVLINK_MCP_URL). Los datos del vehículo devueltos por las herramientas van exclusivamente a su cliente MCP.

Cumplimiento de licencia. El núcleo depende deliberadamente de MAVSDK-Python (BSD-3-Clause) y no de pymavlink (LGPL-3), manteniendo el árbol de dependencias permisivo bajo la licencia MIT de este proyecto. Dependencias directas: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). Todo el código en este repositorio es trabajo original escrito a partir de especificaciones abiertas y públicas (documentos del protocolo MAVLink, documentos de MAVSDK) — sin SDKs propietarios, sin ingeniería inversa, sin EULAs de proveedores aceptadas.

FAQ

¿Necesito un dron? No. MVP1 es simulación primero: todo funciona contra PX4 SITL (un comando Docker) y está diseñado para funcionar también contra ArduPilot SITL. Consulte docs/simulator-quickstart.md.

¿Funciona con ArduPilot? La capa de capacidades apunta tanto a PX4 como a ArduPilot a través de MAVSDK. PX4 SITL es el objetivo principal probado en MVP1; las notas de compatibilidad con ArduPilot SITL están en la guía de inicio rápido, y validarlo en CI es un elemento de la hoja de ruta.

¿Por qué no usar MAVSDK directamente? Si está escribiendo Python a mano, ¡hágalo! mavlink-mcp agrega la capa que MAVSDK no tiene: una superficie de herramientas MCP para agentes de IA, un modelo de capacidades con descubrimiento en tiempo de ejecución y barreras de seguridad de producción (solo lectura, confirmación, geocerca) aplicadas por encima del protocolo.

El agente dice que no se descubrió ningún vehículo. Verifique que SITL se esté ejecutando y enviando MAVLink al endpoint en MAVLINK_MCP_URL (PX4 SITL envía a UDP 14540 por defecto). La guía de inicio rápido tiene una tabla de solución de problemas.

¿Se envían mis datos a algún lugar? Solo a su cliente MCP, que los reenvía al LLM que usted use — trate los datos de posición en consecuencia.

Hoja de ruta

Plan por etapas en ROADMAP.md: MVP1 (esto — capa de capacidades + servidor MCP en SITL), MVP2 (hardware real clase Pixhawk, adaptador ROS 2 reutilizando rosbridge-mcp, sistema de plugins/conformidad), MVP3 (adaptadores comunitarios, multi-vehículo, servicios de núcleo abierto).

Contribuciones

Las contribuciones son bienvenidas — consulte CONTRIBUTING.md. Firme sus commits (DCO). Tenga en cuenta la regla de contribución limpia: las PR deben basarse únicamente en especificaciones y documentación públicas.

Licencia

MIT — consulte LICENSE. Las licencias de las dependencias son permisivas y compatibles: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). Sin dependencias GPL/LGPL/AGPL en el núcleo.

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 capacidades: telemetría (posición/actitud/batería/GPS), modo de vuelo, armado/desarmado, despegue, aterrizaje, ir a, misión, retorno al punto de lanzamiento — 12 herramientas MCP.

• Seguridad por defecto: modo de solo lectura activado (MAVLINK_MCP_READONLY por defecto true); armado y despegue requieren confirm=true tras la aprobación del operador; geocerca suave + techo de altitud configurable.

• Simulación primero: ejecutar con PX4 SITL (1 comando Docker) — ver docs/simulator-quickstart.md. Proyecto destinado a simulación/investigación; el vuelo real es bajo su propia responsabilidad, incluyendo el registro del equipo y la solicitud de permisos de vuelo según la Ley de Defensa Aérea Popular 49/2024 y el Decreto 288/2025.

• El nombre "mavlink-mcp" es provisional — se revisará la política de marcas registradas de Dronecode antes de su publicación.