ardupilot-mavlink-mcp

ardupilot-mcp

一个 MCP 服务，可让 AI Agent 通过 MAVLink 与 ArduPilot 飞行器通信。读取状态、检查和更改参数、切换模式、读取解锁前检查失败原因，以及（受限地）解锁或上锁。优先支持 SITL。

安装：pipx install ardupilot-mavlink-mcp

mcp-name: io.github.rmeadomavic/ardupilot-mavlink-mcp

警告

此工具可以解锁并控制真实飞行器。错误的指令可能导致螺旋桨旋转或飞行器飞离。默认设置旨在防止这种情况：除非传入 --enable-actuation，否则执行控制功能处于关闭状态；即使传入该参数，如果连接不是环回连接（非环回），也会拒绝操作，除非同时传入 --allow-real-vehicle。请使用 SITL 进行开发。对于硬件，请先在拆除螺旋桨的情况下进行台架测试。不提供任何保证——后果由你承担。

为什么

大多数面向大模型的 ArduPilot 工具都用于飞行后的日志分析。这个工具则控制实时链路：连接正在运行的飞行器，读取其状态和参数、切换模式，并诊断无法解锁的原因——即时完成，而不是等到着陆后。典型用法：让 Agent 连接到一架无法解锁的飞行器，读取参数和解锁前的 STATUSTEXT，并告诉你原因，而不必眯着眼睛查看地面控制站（GCS）的消息日志。解锁工具会报告真实的 COMMAND_ACK 结果；如果拒绝解锁，还会返回解锁前的原因；它绝不会强制解锁。

架构

  agent (MCP client)                    ardupilot-mcp                     vehicle
 ┌──────────────────┐   JSON-RPC    ┌──────────────────────┐   MAVLink   ┌──────────┐
 │ Claude / etc.    │ ───stdio────▶ │  FastMCP tools       │ ──udp/tcp/  │ ArduPilot│
 │                  │ ◀───────────  │   │                  │   serial──▶ │  (SITL   │
 └──────────────────┘               │   ▼                  │ ◀────────── │  or FC)  │
                                    │  recv thread (1 reader)            └──────────┘
                                    │   ├─▶ message cache (latest/type)
                                    │   ├─▶ param store (request/collect)
                                    │   └─▶ COMMAND_ACK + STATUSTEXT
                                    └──────────────────────┘

MAVLink 是异步流；MCP 工具则是同步的。一个后台线程负责管理链路，并且是唯一的读取者——它会缓存每种类型的最新消息，并将 PARAM_VALUE 路由到参数存储中。工具调用从这些缓存读取数据（参数操作会阻塞，直到数据到达）。绝不会有两个线程同时调用 recv_match。

功能

• **即时从缓存读取飞行器状态。**模式、是否已解锁、GPS 定位和卫星数、电池、姿态、位置——全部从缓存的遥测数据提供，不会阻塞等待链路响应。
• 诊断无法解锁的原因。ardupilot_arm 会返回 COMMAND_ACK 结果；如果拒绝解锁，还会返回解锁前的 STATUSTEXT（例如 AHRS: waiting for home、Accels inconsistent）。遵守安全检查——不设置 ARMING_CHECK=0，也没有强制解锁的魔法数字。
• 获取和设置真实参数表中的参数，并通过回显的 PARAM_VALUE 确认设置结果。
• 按名称切换飞行模式，并根据飞行器类型（Copter/Rover/Plane/Sub）进行映射——不是硬编码数字。

快速开始（SITL）

你需要一个 ArduPilot SITL 实例。在 ardupilot 检出目录中运行：

# starts ArduCopter SITL; serves MAVLink on tcp:127.0.0.1:5760
sim_vehicle.py -v ArduCopter --console

安装并运行服务（默认只读）：

pipx install ardupilot-mavlink-mcp          # or: uv tool install ardupilot-mavlink-mcp
ardupilot-mavlink-mcp --connect tcp:127.0.0.1:5760

要允许对 SITL 写入参数、更改模式以及解锁/上锁，请添加 --enable-actuation。

与 MCP 客户端配合使用

Claude Code：

claude mcp add ardupilot -- ardupilot-mavlink-mcp --connect tcp:127.0.0.1:5760

Claude Desktop / 任意 mcpServers 配置：

{
  "mcpServers": {
    "ardupilot": {
      "command": "ardupilot-mavlink-mcp",
      "args": ["--connect", "tcp:127.0.0.1:5760"]
    }
  }
}

连接字符串采用 pymavlink 语法：tcp:127.0.0.1:5760（SITL）、udp:127.0.0.1:14550、serial:/dev/ttyACM0:115200。

工具

工具	类型	功能
ardupilot_connect	—	连接到一台载具。默认使用本地 SITL。
ardupilot_vehicle_state	读取	从缓存中读取模式、解锁状态、GPS、电池、姿态和位置。
ardupilot_recent_statustext	读取	获取最近的 STATUSTEXT/预解锁消息。读取此项以查看解锁失败的原因。
ardupilot_get_param	读取	读取一个参数。
ardupilot_set_param	写入	设置一个参数，并通过回显的 PARAM_VALUE 确认。
ardupilot_list_params	读取	列出参数，可选使用 glob（ATC_RAT_*）。
ardupilot_set_mode	写入	按名称发送设置飞行模式的请求。
ardupilot_arm / ardupilot_disarm	写入	受安全门控。通过 COMMAND_ACK 确认。

写入工具受安全门控，并带有 MCP destructiveHint。实时遥测也作为资源 ardupilot://telemetry 提供。

支持的载具

载具	固件	状态
ArduCopter	4.5	✓ 已在 SITL 上验证
ArduRover（UGV/USV）	4.x	~ 已提供模式映射，尚未验证
ArduPlane	4.x	~ 已提供模式映射，尚未验证
ArduSub	4.x	~ 未测试

假定使用 MAVLink2。尚未在硬件上飞行，目前仅在 SITL 上测试。

安全模型

1. 执行器工具默认处于关闭状态。使用 --enable-actuation 启用。
2. 即使已启用，除非同时设置 --allow-real-vehicle，否则仍会拒绝在真实连接（串口或非环回网络）上执行操作。
3. 链路分类采用故障安全策略：任何无法明确判定为环回的连接都会被视为真实载具。
4. arm、disarm、set_param 和 set_mode 都必须通过此安全门控才能发送。
5. 解锁没有强制解锁选项；set_param 在任何连接上都会拒绝写入 ARMING_CHECK（不区分大小写），即使同时启用了两个执行器标志也不例外。

状态

可用功能：读取，以及针对 ArduCopter SITL 的受安全门控参数写入、模式更改和解锁/上锁。已通过三种方式验证：单元测试（Python 3.10–3.12）、真实 MAVLink 线路检查（scripts/wire_check.py）和实时 ArduPilot SITL 运行（scripts/sitl_check.py）。

待处理目标：验证 Rover/Plane/Sub；任务上传/下载和引导飞行（起飞/前往/着陆）暂缓实现——任务协议需要有状态的握手，而引导命令存在飞离风险。请参阅 ROADMAP.md。

开发

git clone https://github.com/rmeadomavic/ardupilot-mcp && cd ardupilot-mcp
uv venv && uv pip install -e ".[dev]"
pytest -q
ruff check . && ruff format --check .
python scripts/wire_check.py            # offline real-wire check, no SITL needed

许可证

MIT — Kyle Adomavicius