AI导哈

FPV无人机MCP平台

一套三个Model Context Protocol服务器，使AI助手能够直接控制FPV无人机硬件，包括无线电发射器配置、飞行控制器调整和黑匣子日志分析。

  • by jir13
  • TypeScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 jir13/MCP

使用说明

FPV无人机MCP平台

三人一套 模型上下文协议 让人工智能助手（克劳德等）直接控制FPV无人机硬件的服务器：无线电发射机配置、飞行控制器调谐和黑匣子日志分析。

Claude ──MCP──┬── betaflight-mcp        ──USB/Serial──► Flight Controller
              ├── tango2-mcp-server     ──SD Card────► TBS Tango 2 Radio
              └── blackbox-mcp-server   ──Filesystem──► Blackbox Logs

建筑

服务器 语言 工具 目的
betaflight mcp Python 66 通过串行MSP协议配置飞行控制器
tango2-mcp服务器 TypeScript 17 TBS Tango 2无线电二进制模型编辑器（FreedomTX .bin)
blackbox mcp服务器 TypeScript 4 Betaflight黑体日志解析器和飞行分析器

总计： 87工具 在3台服务器上，大约8600行代码。

betaflight mcp

使用USB串行与Betaflight飞行控制器通信 MSP协议支持完整配置、遥测和车队管理。

地点： MCP/

能力

  • 连接：自动检测FC，连接/断开/重新连接并重试
  • PID整定：读/写PID设置、RC速率、过滤器配置
  • 模式和开关：配置辅助模式（手臂、角度、水平等）
  • 屏幕显示：使用预设进行完整的OSD布局编辑（自由式、远程、赛车）
  • VTX：频带、信道、功率、坑模式控制
  • 全球定位系统：GPS状态监测、GPS救援配置
  • 安全：飞行前检查、电机测试（个人）、紧急停止、蜂鸣器
  • 车队管理：注册多架无人机，备份所有配置，比较设置
  • 传感器：实时IMU数据、姿态、电池状态、RC通道、电机值
  • 命令行界面：发送原始Betaflight CLI命令，通过以下方式进行备份/还原 diff

处理器模块

MCP/src/betaflight_mcp/
├── server.py          # MCP server + tool definitions + dispatch
├── msp.py             # MSP protocol implementation (v1)
└── handlers/
    ├── connection.py  # Serial port management
    ├── config.py      # PIDs, rates, filters, features, failsafe
    ├── sensors.py     # IMU, attitude, battery, RC, motors
    ├── safety.py      # Preflight, motor test, stop, calibration
    ├── fleet.py       # Multi-drone registry and bulk operations
    ├── osd.py         # OSD layout, elements, presets
    ├── vtx.py         # Video transmitter settings
    └── gps.py         # GPS status and rescue config

设置

cd MCP
python -m venv venv
source venv/bin/activate
pip install -e .

MCP配置

{
  "mcpServers": {
    "betaflight": {
      "command": "MCP/venv/bin/python",
      "args": ["-m", "betaflight_mcp"]
    }
  }
}

环境变量

变量 默认值 描述
BETAFLIGHT_FLEET_REGISTRY ~/.drone/fleet.json 车队注册路径
BETAFLIGHT_BACKUP_DIR ~/.drone/backups/betaflight/ CLI备份目录

tango2-mcp服务器

直接在二进制级别读取和写入TBS Tango 2无线电模型文件。收音机安装为USB大容量存储设备，此服务器编辑 .bin SD卡上的模型文件。

地点： tango2-mcp-server/

能力

  • 无线电探测：自动检测跨macOS/Windows/Linux的Tango 2挂载点
  • 模型管理：列出、阅读、创建、比较、验证模型
  • 混音编辑器：设置混音，为AUX通道分配开关（SA-SF）
  • 定时器配置：配置飞行计时器（倒计时、油门触发等）
  • 模板：从预设（自由式、远程、电影）创建模型
  • 备份/恢复：具有路径遍历保护的备份模型，从备份还原
  • 备份轮换：自动清理，每个模型保留最后N个备份
  • 原始调试：十六进制转储二进制文件的任何部分

二进制格式（otx5）

解析器处理FreedomTX/OpenTX 2.3二进制格式：

Offset  Size  Field
0x00    4     Fourcc "otx5"
0x04    10    Model name (ASCII)
0x0E    1     Model ID (5 bits)
0x0F    48    3 timers x 16 bytes (bitpacked: mode, start, countdown, persistent)
0x43    1280  64 mixes x 20 bytes (weight, destCh, srcRaw, offset, switch, curves, name)

MIXSRC编号：I1-I32（1-32），LUA（33-74），MAX（75），摇杆：舵=79/Ele=80/Thr=81/Ail=82，锅：S1=83/S2=84，开关：SA=89.SF=94，通道：Ch1=95+

设置

cd tango2-mcp-server
npm install
npm run build

MCP配置

{
  "mcpServers": {
    "tango2": {
      "command": "node",
      "args": ["tango2-mcp-server/dist/index.js"]
    }
  }
}

环境变量

变量 默认值 描述
TANGO2_BACKUP_DIR ~/.drone/backups/tango2/ 模型备份目录

blackbox mcp服务器

解析Betaflight黑体日志(.bbl, .bfl, .txt)并为飞行分析提供问题检测和调整建议。

地点： blackbox-mcp-server/

能力

  • 日志发现：列出任何目录中带有大小和日期信息的黑盒文件
  • 飞行分析：分析日志并检测振动问题、PID问题、去同步事件
  • 时间序列：通过下采样提取通道数据（陀螺仪、设定点、电机、RC）
  • 频道列表：在日志文件中发现可用的数据通道

支持格式

扩展 来源 典型尺寸
.bbl 板载闪存（BetaFPV等） 25 KB-500 KB
.bfl SD卡记录 1 MB-50 MB
.txt OpenLog/Blacbox Explorer导出 5 MB-100 MB

设置

cd blackbox-mcp-server
npm install
npm run build

MCP配置

{
  "mcpServers": {
    "blackbox": {
      "command": "node",
      "args": ["blackbox-mcp-server/dist/index.js"]
    }
  }
}

环境变量

变量 默认值 描述
BLACKBOX_LOG_DIR ~/blackbox-logs 默认日志搜索目录
MAX_FILE_SIZE 104857600 （100 MB） 最大可解析文件大小

统一备份结构

所有三台服务器都将备份存储在 ~/.drone/:

~/.drone/
├── backups/
│   ├── tango2/        # Radio model .bin backups (timestamped)
│   ├── betaflight/    # FC CLI diff backups (.txt)
│   ├── blackbox/      # Analyzed log archive
│   └── mcp-config/    # Claude MCP config snapshots
└── fleet.json         # Multi-drone fleet registry

标准程序

连接无人机时的推荐工作流程（根据CLAUDE.md）：

  1. 备份配置 — backup_configuration （贝塔飞行）+ backup_model （汤2）
  2. 检查日志和黑匣子 — analyze_blackbox_log 最近的航班
  3. 给予反馈 --AI审查PID调整、过滤器设置和飞行数据，以提出改进建议

测试

# Tango2 binary parser — 75 tests (vitest)
cd tango2-mcp-server && npm test

# Betaflight MSP protocol — 18 tests (pytest)
cd MCP && source venv/bin/activate && python -m pytest tests/ -v

测试覆盖范围：

  • FTX模型文件：构造函数验证、名称获取/设置、计时器往返、混合读/写、srcRaw映射、dumpRaw边界检查、保存持久性
  • MSP协议：校验和计算、消息构建、响应解析、错误处理（超时、标头错误、代码错误、校验和损坏）
  • 整合：完全创建→ 配置→ 备份→ 修改→ 恢复→ 验证周期

安全

  • 路径遍历保护 上 restore_model --根据备份目录验证解析路径
  • ASCII输入验证 在所有二进制写入时--防止损坏的模型文件包含不可打印的字符
  • 边界检查 在原始内存读取时——根据文件大小验证偏移量+长度
  • 受保护的备份 --在对原始文件进行任何修改之前抛出备份失败

硬件

测试方法：

  • 收音机：TBS Tango 2（FreedomTX固件）
  • 飞行控制员：iFlight闪电战F722，BetaFPV F722
  • 无人机：iFlight Chimera 7 Pro V2（长距离），iFlight Nazgul Evoque F6（自由式）
  • 协议：TBS交火（CRSF）
  • 平台：macOS ARM（苹果硅）

许可证

麻省理工学院

相关 MCP