mavlink-mcp

mavlink-mcp — это вендор-нейтральный уровень возможностей UAV + сервер Model Context Protocol, построенный на открытых стандартах. Он подключает AI-агентов (Claude Desktop, Cursor, VS Code и любой другой клиент MCP) к дронам, которые говорят на MAVLink — PX4 SITL, ArduPilot SITL и автопилоты класса Pixhawk — через MAVSDK (BSD-3-Clause). Вместо обёртывания протокольных сообщений он предоставляет 8 возможностей полёта (телеметрия, режим полёта, arm/disarm, взлёт, посадка, goto, миссия, возврат на точку старта) за одним чистым API с включенными по умолчанию защитными ограничениями.

Это сестринский проект rosbridge-mcp (AI-агенты ↔ роботы ROS 2) и разделяет его философию: только открытые протоколы, защитные ограничения по умолчанию в режиме только чтения, сначала симуляция, нулевая телеметрия, лицензия MIT.

Примечание о названии: «mavlink-mcp» — рабочее название. «MAVLink» является товарным знаком Dronecode Foundation; название проекта может быть скорректировано после рассмотрения их политики использования товарных знаков перед любым публичным релизом.

Отказ от ответственности: этот проект создан для симуляции и исследований. Полёты на реальных летательных аппаратах осуществляются исключительно на ваш собственный риск и под вашу ответственность, включая соблюдение местного авиационного законодательства (регистрация, разрешения на полёты, лицензирование пилотов). См. SECURITY.md.

Зачем уровень возможностей, а не очередной SDK?

• Для AI-агентов возможности лучше, чем 400 функций SDK. Агент запрашивает get_capabilities («что умеет этот дрон?»), получает небольшой словарь физических действий и планирует с ним — никаких знаний MAVLink на стороне модели не требуется.

• Вендор-нейтральность по построению. Возможности определены в физических величинах (градусы, метры, вольты) из открытых спецификаций — не скопированы с поверхности какого-либо проприетарного SDK. Адаптер MAVSDK — одна реализация; будущий адаптер 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), затем добавьте в конфигурацию вашего MCP-клиента:

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

Затем спросите вашего агента: «Что умеет этот дрон и где он сейчас?»

Когда будете готовы лететь (в симуляторе!), установите MAVLINK_MCP_READONLY в "false".

Возможности и инструменты

12 инструментов, покрывающих 8 возможностей. Все инструменты возвращают JSON; ошибки возвращаются в виде {"error": "...", "guardrail": true} вместо исключений, чтобы агент мог прочитать и отреагировать.

Пример диалога

Вы: Проверь дрон, и если он в порядке, соверши короткий патруль на высоте 20 м.

Агент: (вызывает get_capabilities — видит, что режим только чтения выключен, геозона 200 м; вызывает get_telemetry — GPS FIX_3D, 10 спутников, батарея 100%) Дрон в порядке. Мне нужно ваше одобрение на вооружение и взлёт — подтверждаете?

Вы: Подтверждаю, действуйте.

Агент: (вызывает arm(confirm=true), takeoff(altitude_m=20, confirm=true), затем fly_mission с 3 путевыми точками внутри геозоны, отслеживает get_telemetry, завершает return_to_launch) Патруль завершён — дрон вернулся на точку старта и разоружён.

Конфигурация

Безопасность

Позволить языковой модели управлять летательным аппаратом — реальный риск, поэтому защитные ограничения строже, чем в типичном SDK:

1. Только чтение по умолчанию. В отличие от большинства инструментов, вы должны явно дать согласие на полёт с помощью MAVLINK_MCP_READONLY=false. В режиме только чтения все инструменты телеметрии работают; каждый мутабельный инструмент отклоняется с понятным объяснением.

2. Двухшаговое подтверждение для опасных переходов. arm и takeoff требуют confirm=true, и описания инструментов предписывают агенту сначала получить одобрение человека — агент не может легитимно взлететь за один автономный шаг.

3. Мягкий геозон + потолок высоты. Каждая команда с координатами (goto и каждая путевая точка миссии) проверяется относительно MAVLINK_MCP_GEOFENCE_RADIUS_M вокруг дома и MAVLINK_MCP_MAX_ALTITUDE_M перед отправкой автопилоту.

4. Действия по безопасности остаются без барьеров. land, hold и return_to_launch никогда не требуют подтверждения — деэскалация всегда должна быть лёгкой.

Эти проверки являются политикой внутри данного процесса — не заменой собственных средств безопасности автопилота, реального геозона, настроенного в PX4/ArduPilot, сетевой изоляции или человека с RC-передатчиком. Прочитайте SECURITY.md перед рассмотрением реального оборудования и рассматривайте полёты в реальном мире как требующие регистрации/разрешений в соответствии с местным авиационным законодательством (например, Вьетнамский Указ о БПЛА 288/2025 требует регистрации и разрешений на полёты).

Библиотека Python

Тот же уровень возможностей можно импортировать для скриптов и блокнотов — см. examples/patrol_sitl.py для полного цикла взлёт → путевые точки → посадка на 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)

Конфиденциальность и юридические аспекты

Никакой телеметрии, никакого сбора данных. Единственное сетевое соединение, которое открывает этот пакет — это конечная точка 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.

Часто задаваемые вопросы

Нужен ли мне дрон? Нет. MVP1 ориентирован на симуляцию: всё работает против PX4 SITL (одна команда Docker) и спроектировано для работы также против ArduPilot SITL. См. docs/simulator-quickstart.md.

Работает ли он с ArduPilot? Уровень возможностей нацелен как на PX4, так и на ArduPilot через MAVSDK. PX4 SITL является основным протестированным целевым объектом в MVP1; заметки о совместимости с ArduPilot SITL находятся в кратком руководстве, а проверка в CI — пункт дорожной карты.

Почему бы не использовать MAVSDK напрямую? Если вы пишете Python вручную — используйте! mavlink-mcp добавляет уровень, которого нет в MAVSDK: поверхность инструментов MCP для AI-агентов, модель возможностей с обнаружением во время выполнения и производственные защитные ограничения (только чтение, подтверждение, геозон), применяемые над протоколом.

Агент говорит, что транспортное средство не обнаружено. Проверьте, что SITL запущен и отправляет MAVLink на конечную точку, указанную в MAVLINK_MCP_URL (PX4 SITL по умолчанию отправляет на UDP 14540). В кратком руководстве есть таблица устранения неполадок.

Передаются ли мои данные куда-либо? Только вашему MCP-клиенту, который пересылает их той LLM, которую вы используете — обращайтесь с данными о положении соответственно.

Дорожная карта

Поэтапный план в ROADMAP.md: MVP1 (этот — уровень возможностей + MCP сервер на SITL), MVP2 (реальное оборудование класса Pixhawk, адаптер ROS 2, повторно использующий rosbridge-mcp, система плагинов/соответствия), MVP3 (адаптеры сообщества, несколько транспортных средств, сервисы с открытым ядром).

Участие в разработке

Вклады приветствуются — см. CONTRIBUTING.md. Пожалуйста, подписывайте свои коммиты (DCO). Обратите внимание на правило чистого вклада: PR должны быть основаны только на публичных спецификациях и документации.

Лицензия

MIT — см. LICENSE. Лицензии зависимостей являются разрешительными и совместимыми: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). В ядре нет зависимостей GPL/LGPL/AGPL.

Краткое содержание на русском

mavlink-mcp — это вендор-нейтральный уровень возможностей для БПЛА с MCP-сервером, построенный полностью на открытых стандартах: подключает AI-агентов (Claude Desktop, Cursor, VS Code...) к дронам, общающимся на MAVLink (PX4/ArduPilot), через библиотеку MAVSDK (BSD-3). Это проект-близнец rosbridge-mcp.

• 8 возможностей: телеметрия (позиция/ориентация/заряд батареи/GPS), режим полета, взведение/снятие, взлет, посадка, переход, миссия, возврат на базу — 12 инструментов MCP.

• Безопасность по умолчанию: режим только для чтения включен по умолчанию (MAVLINK_MCP_READONLY по умолчанию true); для взведения и взлета требуется confirm=true после согласия оператора; мягкий геозон + настраиваемый потолок высоты.

• Симуляция в первую очередь: запуск с PX4 SITL (одна команда Docker) — см. docs/simulator-quickstart.md. Проект предназначен для симуляции/исследований; реальные полеты полностью на вашей ответственности, включая регистрацию устройства и получение разрешения на полет в соответствии с Законом о народной противовоздушной обороне 49/2024 и Постановлением 288/2025.

• Название "mavlink-mcp" временное — будет проверена политика товарных знаков Dronecode перед публикацией.