ardupilot-mcp

ardupilot-mcp

土耳其语 · English

用于诊断 ArduPilot 飞行日志的 MCP 服务。将它添加到 Claude Desktop、Cursor 或 VS Code 等 AI 客户端，再提供 .bin 或 .tlog 文件；客户端就会用通俗的语言解释飞行中发生了什么：振动、电池电量低、GPS 丢失、电机故障、配置错误。

诊断结果由确定性检查生成。每项阈值的来源都列在 docs/SOURCES.md 中；模型只负责解释这些结果。服务只读取本地文件，不连接网络、不向飞行器发送命令，也不写入参数。

快速开始

使用 Claude Desktop：

1. 安装 uv。
2. 在 Claude Desktop 中通过 Settings → Developer → Edit Config 添加以下内容：

   { "mcpServers": { "ardupilot-mcp": { "command": "uvx", "args": ["ardupilot-mcp"] } } }
   

3. 完全退出并重新打开 Claude Desktop。
4. 提问："分析 C:\loglar\00000042.BIN 日志，看看它为什么坠毁？"

使用 Claude Code 只需一行：claude mcp add ardupilot-mcp -- uvx ardupilot-mcp。Cursor、VS Code、Windsurf、Cline、Zed、LM Studio 和其他客户端的配置、故障排查以及无客户端试用方法，见 docs/clients.md。

哪种日志？

• .bin 是飞行控制器自身记录的日志，可提供最详细的诊断。它位于 SD 卡的 APM/LOGS/ 文件夹中；也可以在 Mission Planner 中通过 DataFlash Logs → Download DataFlash Log Via Mavlink 下载。
• .tlog 是地面站记录的遥测数据。它每秒只有几条样本，且只包含主要传感器，因此诊断较为粗略。可能会把无线电连接中断误判为飞行器故障的检查不会处理此类文件。

示例

以下是运行 python examples/analyze.py demo.bin 后输出的部分内容。客户端会用你的语言描述相同的诊断结果。

First anomaly while armed: Elevated VibeZ vibration @ 9s.
6 critical, 2 warning, 3 info finding(s).
[CRITICAL] vibration @ 9s: Elevated VibeZ vibration
           VibeZ vibration peaks at 72 m/s^2 (>60); 20% of samples exceed 60 m/s^2.
[CRITICAL] attitude  @ 20s: Attitude tracking failure (roll)
           Roll failed to track the demand for 3.0 s, error up to 35 deg (sustained >25 deg).
[CRITICAL] power     @ 25s: Battery reached critical voltage
           Pack voltage fell to 13.32 V, at or below the critical-voltage level (13.50 V, configured BATT_*_VOLT failsafe).

工具

所有工具都为只读。

工具	用途
analyze_log	运行所有检查；按重要性排序并附上 ArduPilot 官方文档链接，返回诊断结果。
incident_timeline	找出首次异常和坠机时刻，并按时间顺序排列事件。不推断因果关系。
forum_report	生成可粘贴到 discuss.ardupilot.org 的 Markdown 回复。不包含 GPS 位置。
compare_logs	并排比较两次飞行之间发生变化的参数、固件和指标。
log_summary	飞行器、固件、时长、飞行模式和日志完整性。
vehicle_profile	机架、电机数量、电池、悬停油门和动力余量。
list_events	ERR、MODE、EV 和 MSG 记录的时间线。
query_timeseries	查看某项诊断结果背后的原始序列；对于多传感器，可选择实例。
get_params	获取日志中的参数，以及该固件版本文档记录的范围、单位和值。
load_param_file	读取导出的 .param 文件。
recommend_tuning	给出谐波 notch、PID 和 autotune 建议，不会应用任何更改。
list_checks	列出已注册的检查。

工具参数和全部 18 项检查见 docs/reference.md。该文件由 scripts/gen_docs.py 从代码生成，CI 也会检查其是否为最新版本。

工作原理

解析器会将日志转换为列式 FlightLog 模型。已注册的检查会读取此模型：日志中没有相关数据的检查会跳过，不适用于该机型的检查不会运行。同一事件的 ERR 记录、failsafe 模式变更和固件消息会合并为一条发现。坠机后才开始的发现会移至列表末尾，报告开头则保留坠机前出现的首个异常。

4.x 固件会用同一个消息名称记录每个 IMU、GPS、罗盘、电池和 EKF 核心。检查会分别评估它们。对于 4.1 之前的日志，以独立名称记录的次级传感器也会转换为相同结构。

服务基于 MCP Python SDK 2 运行。它既支持 2026-07-28 协议版本，也支持如今大多数桌面客户端使用的旧版握手（2024-11-05 至 2025-11-25）。

准确性与限制

引擎以论坛上的 49 份真实事故日志进行评测；每份日志的原因均由检查该日志的开发者或资深用户撰写。当前分数和方法见 bench/README.md。

• 尚不能检测由罗盘航向误差引起的环形漂移（toilet-bowl）。
• 格式定义损坏的日志会返回明确错误，而非部分结果。
• .tlog 文件不包含 ERR 记录、batch sampler、快速 IMU 和模式变更原因。
• 发现结果仅用于辅助决策，不会判断飞行器是否适航。

其他工具

UAV Log Viewer 和 Mission Planner 的 Auto Analysis 会展示数据，解读工作则留给你。ardupilot-mcp 会进行解读并回答后续问题。若要在图表中查看信号或以 3D 方式跟踪飞行，UAV Log Viewer 更合适。

贡献

CONTRIBUTING.md 介绍开发环境、如何添加新检查以及 PR 流程。AI 助手遵循的规则见 AGENTS.md。请按照 SECURITY.md 中的方式报告安全漏洞。变更记录见 CHANGELOG.md。

许可证

GNU AGPL-3.0。如果你修改代码并通过网络将其作为服务提供，就必须向该服务的用户公开修改后的源代码。如果 AGPL 条款不适合你的用途，请发送邮件至 [email protected] 咨询商业许可证。PyPI 上发布的 0.1.3 及更早版本采用 MIT 许可证，并继续保持不变；此变更之后的源代码及后续版本均采用 AGPL-3.0 许可证。

ardupilot_mcp/data/params/ 下的数据由 ArduPilot 的 GPLv3 许可参数定义（apm.pdef.xml）中提取的事实组成：范围、单位、值代码和位掩码位。不复制说明文本。