内容
# ardupilot-mcp
MCP服务器，允许AI代理通过MAVLink与ArduPilot飞行器通信。读取状态、检查和更改参数、切换模式、读取预备失败信息，以及（受限）启用或禁用。优先支持SITL。
安装：`pipx install ardupilot-mavlink-mcp`
`mcp-name: io.github.rmeadomavic/ardupilot-mavlink-mcp`
[](https://pypi.org/project/ardupilot-mavlink-mcp/)
> [!WARNING]
> **该工具可以启用和控制真实飞行器。** 错误的命令可能会导致螺旋桨旋转或飞行器飞走。 默认配置阻止这种情况发生：除非您传递 `--enable-actuation`，否则执行是关闭的；即使那样，除非您还传递 `--allow-real-vehicle`，否则它也不会接受真实（非回环）链接。 在SITL上开发。 在硬件上，先在**关闭螺旋桨**的情况下进行台架测试。 无保修 — 您自行承担后果。
## 为什么
大多数用于LLM的ArduPilot工具都针对飞行后日志分析。这个工具则驱动**实时链接**：连接到正在运行的飞行器，读取其状态和参数，改变模式，并在出现问题时进行诊断 — 不是在着陆后，而是在当时。 实用场景：指向一个无法启用的飞行器，让它读取参数和预备`STATUSTEXT`，并告诉您原因，而不是您盯着GCS消息日志。启用工具报告真正的`COMMAND_ACK`结果，并在拒绝时返回预备原因；它永远不会强制启用。
## 架构
```
代理（MCP客户端） ardupilot-mcp 飞行器
┌──────────────────┐ JSON-RPC ┌──────────────────────┐ MAVLink ┌──────────┐
│ Claude / 等 │ ───stdio────▶ │ FastMCP 工具 │ ──udp/tcp/ │ ArduPilot│
│ │ ◀─────────── │ │ │ 串行──▶ │ （SITL │
└──────────────────┘ │ ▼ │ ◀────────── │ 或FC） │
│ 接收线程（1个读取器） └──────────┘
│ ├─▶ 消息缓存（最新/类型）
│ ├─▶ 参数存储（请求/收集）
│ └─▶ COMMAND_ACK + STATUSTEXT
└──────────────────────┘
```
MAVLink是异步流；MCP工具是同步的。 一个后台线程拥有链接，并且是唯一的读取器 — 它缓存每个类型的最新消息，并将`PARAM_VALUE`路由到参数存储。 工具调用从这些缓存中读取（参数在数据到达之前阻塞）。 两个线程永远不会调用`recv_match`。
## 功能
- **立即从缓存中读取飞行器状态。** 模式、启用、GPS修复和卫星数量、电池、姿态、位置 — 从缓存的遥测数据中提供，不会阻塞链接。
- **诊断启用失败。** `ardupilot_arm`返回`COMMAND_ACK`结果，并在拒绝时返回预备`STATUSTEXT`（例如`AHRS: waiting for home`，`Accels inconsistent`）。 尊重安全检查 — 不允许`ARMING_CHECK=0`，没有强制启用神奇数字。
- **获取和设置参数** 在真实的参数表中，`set`通过回显的`PARAM_VALUE`确认。
- **切换飞行模式** 按名称，映射到每个飞行器类型（Copter/Rover/Plane/Sub） — 不是硬编码的数字。
## 快速入门（SITL）
您需要一个ArduPilot SITL实例。 从`ardupilot`检出：
```bash
# 启动ArduCopter SITL； 在tcp:127.0.0.1:5760上提供MAVLink
sim_vehicle.py -v ArduCopter --console
```
安装并运行服务器（默认只读）：
```bash
pipx install ardupilot-mavlink-mcp # 或：uv tool install ardupilot-mavlink-mcp
ardupilot-mavlink-mcp --connect tcp:127.0.0.1:5760
```
要允许参数写入、模式更改和SITL启用/禁用，请添加 `--enable-actuation`。
## 与MCP客户端一起使用
Claude 代码：
```bash
claude mcp add ardupilot -- ardupilot-mavlink-mcp --connect tcp:127.0.0.1:5760
```
Claude 桌面 / 任意 `mcpServers` 配置：
```json
{
"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` | 读取 | 列出参数，可选通配符（`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](ROADMAP.md).
## 开发
```bash
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 # 离线真实线路检查，不需要SITL
```
## 许可证
[MIT](LICENSE) — Kyle Adomavicius
