mavlink-mcp

mavlink-mcp 是一个供应商中立的无人机能力层 + 模型上下文协议服务器，完全基于开放标准构建。它通过 MAVSDK (BSD-3-Clause) 将 AI 代理（Claude Desktop、Cursor、VS Code 以及任何其他 MCP 客户端）连接到支持 MAVLink 的无人机——PX4 SITL、ArduPilot SITL 和 Pixhawk 级自动驾驶仪。它不是封装协议消息，而是将 8 项飞行能力（遥测、飞行模式、解锁/上锁、起飞、降落、飞往指定点、任务、返航）暴露在同一个整洁的 API 后面，并默认启用安全护栏。

它是 rosbridge-mcp（AI 代理 ↔ ROS 2 机器人）的姊妹项目，并共享相同的理念：仅开放协议、默认只读的安全护栏、模拟优先、零遥测、MIT 许可证。

关于名称的说明： "mavlink-mcp" 是一个临时的工作名称。"MAVLink" 是 Dronecode 基金会的商标；项目名称可能会在公开发布前根据其商标政策的审查结果进行调整。

安全免责声明： 本项目是为模拟和研究而构建的。使用它驾驶真实飞行器完全由您自行承担风险和责任，包括遵守当地航空法律（注册、飞行许可、飞行员执照）。请参阅 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)，然后使用地理围栏内的 3 个航点调用 fly_mission，监控 get_telemetry，最后调用 return_to_launch) 巡逻完成——无人机已返回起飞点并已上锁。

配置

安全

让语言模型指挥飞行器是真实的风险，因此安全护栏比典型的 SDK 更严格：

1. 默认只读。 与大多数工具不同，您必须通过 MAVLINK_MCP_READONLY=false 明确选择才能飞行。在只读模式下，所有遥测工具都可用；每个会修改状态的工具都会被拒绝，并附有清晰说明。

2. 危险转换需要两步确认。 arm 和 takeoff 需要 confirm=true，工具描述指示代理首先获得人类批准——代理无法在单个自主步骤中合法起飞。

3. 软地理围栏 + 高度上限。 每个命令的位置（飞往指定点和每个任务航点）在发送到自动驾驶仪之前，都会根据 MAVLINK_MCP_GEOFENCE_RADIUS_M（围绕起飞点）和 MAVLINK_MCP_MAX_ALTITUDE_M 进行验证。

4. 安全操作保持无摩擦。 land、hold 和 return_to_launch 永远不需要确认——降级操作必须始终廉价。

这些检查是此进程内部的策略——不能替代自动驾驶仪自身的故障保护、在 PX4/ArduPilot 中配置的真实地理围栏、网络隔离或持遥控器的人类操作员。在考虑真实硬件之前，请阅读 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 一起工作吗？ 能力层通过 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（当前——能力层 + MCP 服务器在 SITL 上）、MVP2（真实 Pixhawk 级硬件、重用 rosbridge-mcp 的 ROS 2 适配器、插件/一致性系统）、MVP3（社区适配器、多机、开放核心服务）。

贡献

欢迎贡献——请参阅 CONTRIBUTING.md。请签署您的提交（DCO）。注意清洁贡献规则：PR 必须仅基于公共规范和文档。

许可证

MIT——参见 LICENSE。依赖项许可证是宽松且兼容的：mavsdk (BSD-3-Clause)、fastmcp (Apache-2.0)。核心中没有 GPL/LGPL/AGPL 依赖项。

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 项能力： 遥测（位置/姿态/电量/GPS）、飞行模式、解锁/锁定、起飞、降落、前往、任务、返航 — 12 个 MCP 工具。

• 默认安全： 只读模式默认开启（MAVLINK_MCP_READONLY 默认 true）；解锁和起飞需在操作员同意后设置 confirm=true；可配置软禁飞区和高度上限。

• 仿真优先： 使用 PX4 SITL 运行（1 条 Docker 命令） — 参见 docs/simulator-quickstart.md。该项目适用于仿真/研究；实际飞行完全由您自行负责，包括根据《人民防空法 49/2024》和《288/2025 法令》进行设备注册和飞行许可申请。

• 名称“mavlink-mcp”为暂定名称 — 将在发布前根据 Dronecode 的商标政策进行审查。