AI导哈

无人机控制协议服务器

用于控制ArduPilot兼容无人机的MCP-to-HTTP协议转换服务器，提供飞行控制、GPS导航和实时遥测功能。

  • by Project-GrADyS
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 Project-GrADyS/uav_mcp

使用说明

无人机MCP

MCP服务器，用于控制与ArduPilot兼容的无人机（QuadCopters）。 uav_mcp 很瘦 MCP到HTTP垫片 它将无人机的指令、运动和遥测作为MCP工具公开，并将所有车辆逻辑委托给 uav_api HTTP服务器。由 官方Python MCP SDK，通过流式HTTP在 /mcp通过MAVLink支持真实无人机，通过ArduPilot SITL支持模拟无人机。

特征：

  • MCP工具界面 在 /mcp --连接任何MCP客户端（Claude Desktop、Claude Code、LangGraph、自定义代理）以控制无人机
  • 全飞行控制：手臂和起飞在一个指令
  • GPS和NED移动命令（即发即弃和封锁变体）
  • 丰富的遥测技术：GPS、NED位置、指南针、电池、传感器健康状况
  • 两种运行模式： 嵌入 （产生自己的 uav-api)或 外部 （指向跑步 uav-api)
  • Gradys地面站集成和任务规划器流是 uav-api

建筑

MCP client  ──HTTP /mcp──►  uav-mcp  ──HTTP──►  uav-api  ──MAVLink──►  Vehicle / SITL
  • uav-mcp 仅拥有MCP传输。每个工具都是一个 async 发出一个（或两个，用于 arm_and_takeoff)HTTP调用 uav-api 并将响应JSON返回给MCP客户端。
  • uav-api 拥有MAVLink连接、排水循环、SITL生成、Gradys GS推送和脚本执行。
  • 在 嵌入式模式 （默认）， uav-mcp 生成 uav-api 作为专用端口上的子进程（默认 8001)并在关机时将其撕下。
  • 在 外部模式 (--uav_api_url), uav-mcp 连接到单独运行的 uav-api 并且不会繁殖或杀死它。

安装

先决条件

  • Python 3.10+
  • uav-api 已安装并打开 PATH （作为依赖关系引入）
  • 对于模拟飞行：本地构建的ArduPilot存储库，以及 xterm 安装。
    • 克隆并构建ArduPilot：https://ardupilot.org/dev/docs/where-to-get-the-code.html
    • SITL设置指南：https://ardupilot.org/dev/docs/SITL-setup-landingpage.html

从PyPI安装（推荐）

pip install uav-mcp

安装后重新启动终端。

从源代码安装（开发）

git clone https://github.com/Project-GrADyS/uav_mcp
cd uav_mcp
pip install -e .

安装后重新启动终端。

入门指南

嵌入式模式（默认）——真实无人机

uav-mcp 生成 uav-api 内部端口 8001 并通过MAVLink连接到您的车辆：

uav-mcp --port 8000 --uav_connection 127.0.0.1:17171 --connection_type udpin --sysid 1

这 --connection_type 控制UDP方向（传递到 uav-api):

  • udpin --服务器监听，无人机连接（最常见）
  • udpout --服务器连接到无人机
  • usb --串行连接（组 --uav_connection 到串行设备路径，例如。 /dev/ttyUSB0)

嵌入式模式——仿真（SITL）

uav-mcp 生成 uav-api，这反过来又催生了新的ArduCopter SITL xterm 窗口：

uav-mcp --simulated true --ardupilot_path ~/ardupilot --speedup 1 --port 8000 --sysid 1

SITL绑定到中的地址 --uav_connection （默认值 127.0.0.1:17171).这 --speedup 因素控制模拟速度（例如。 5 =5倍实时）。 --location 设置SITL起始位置（默认 AbraDF).

外部模式——指向正在运行的无人机api

适用于多MCP设置、调试或共享 uav-api 跨客户。跑 uav-api 你自己：

uav-api --simulated true --ardupilot_path ~/ardupilot --port 9000 --sysid 1

然后点 uav-mcp 在它：

uav-mcp --port 8000 --uav_api_url http://localhost:9000 --sysid 1

在外部模式下， uav-mcp 做 不 产卵或杀死 uav-api，并忽略所有传递参数，除了 --sysid （用于标记响应）。

使用配置文件

所有参数都可以通过INI文件提供：

[api]
port=8000
uav_connection=127.0.0.1:17171
connection_type=udpin
sysid=1

[simulated]
ardupilot_path=~/ardupilot
location=AbraDF
gs_connection=[]
speedup=1

[logs]
log_console=[]
log_path=None
debug=[]
script_logs=None

运行方式：

uav-mcp --config /path/to/config.ini

CLI参数始终覆盖配置文件中的值。

启动和关闭生命周期

初创公司 (uav_mcp/run_mcp.py):

  1. CLI参数被解析并序列化到 UAV_ARGS 有人是。
  2. 如果 --uav_api_url 未设置： uav-api 作为标记为的子流程生成 UAV_MCP_API_TAG=MCP_API_<sysid> 以便以后拆卸。 uav-api 然后处理SITL生成、MAVLink连接、排水回路和（如果 --gradys_gs 设置）GS按钮。
  3. wait_for_uav_api(...) 民意调查 http://<host>:<port>/docs 直到准备就绪（超时120秒）。
  4. 共享 aiohttp.ClientSession 在 uav_api_client 已初始化。
  5. MCP服务器开始监听 --port (mcp.run_streamable_http_async()).

关机 （在Ctrl+C或SIGTERM上）：

  1. MCP服务器停止接受请求。
  2. 这 aiohttp 会话已关闭。
  3. 如果 uav-api 已生成： kill_uav_api_by_tag 扫描 psutil.process_iter 适用于环境承载的过程 UAV_MCP_API_TAG=MCP_API_<sysid> 并杀死他们——这让他们俩都倒下了 uav-api 以及它产生的任何SITL进程。

验证MCP服务器

服务器运行后，您可以通过连接LLM代理进行验证。

使用克劳德桌面

将MCP服务器添加到Claude Desktop配置中(claude_desktop_config.json):

{
  "mcpServers": {
    "uav-1": { "url": "http://localhost:8000/mcp" }
  }
}

重新启动Claude Desktop，然后问：

“获取无人机的通用遥测数据”

克劳德会打电话给 get_general_telemetry 工具和返回空速、地速、航向、油门和高度——确认MCP服务器已连接到车辆。

使用克劳德代码

创建一个 .mcp.json 项目目录中的文件：

{
  "mcpServers": {
    "uav-1": { "url": "http://localhost:8000/mcp" }
  }
}

然后启动Claude Code，让它与无人机交互：

“武装无人机，起飞至20米”

克劳德代码将调用 arm_and_takeoff 和 alt=20.

多无人机设置

每架无人机运行一个MCP服务器，每个服务器都有自己的 uav-api 在一个独特的内部端口上：

uav-mcp --simulated true --ardupilot_path ~/ardupilot --port 8001 --uav_api_port 9001 --sysid 1
uav-mcp --simulated true --ardupilot_path ~/ardupilot --port 8002 --uav_api_port 9002 --sysid 2

为MCP客户端配置两台服务器：

{
  "mcpServers": {
    "uav-1": { "url": "http://localhost:8001/mcp" },
    "uav-2": { "url": "http://localhost:8002/mcp" }
  }
}

然后，LLM代理可以通过调用每个服务器上的工具来控制多架无人机。

MCP工具

工具分为三组：

命令： arm_and_takeoff, rtl --手臂/起飞并返回发射。

运动： go_to_gps, go_to_gps_wait, go_to_ned, go_to_ned_wait, drive, drive_wait, stop, resume -全球定位系统和NED导航与即发即弃和封锁变体。

遥测： get_general_telemetry, get_gps, get_ned, get_compass, get_sys_status, get_sensor_status, get_battery, get_home --读取车辆状态和传感器数据。

每个工具向匹配对象发出一个HTTP调用 uav-api 端点(arm_and_takeoff 问题二： /command/arm 然后 /command/takeoff)并逐字返回响应JSON。在HTTP错误时，该工具返回 {"device":"uav","id":"<sysid>","error":"<TOOL> FAIL: <detail>"}.

看 .claude/docs/specification.md 有关完整参数和响应的详细信息。

CLI参数参考

跑 uav-mcp --help 以供快速参考。

uav_mcp拥有的参数

参数 默认值 描述
--config 无 INI配置文件的路径([api], [simulated], [logs] 部分）
--port 8000 MCP服务器监听的端口（流式HTTP）
--uav_api_url 无 已运行的URL uav-api当设置时， uav-mcp 连接到它，而不产生自己的。
--uav_api_port 8001 移植已生成的 uav-api 子进程正在监听。当 --uav_api_url 已设置。

通过到 uav-api

这些信息会逐字转发给 uav-api 子进程（在外部模式下忽略，除非 --sysid).

参数 默认值 描述
--sysid 10 MAVLink系统ID；必须与无人机匹配 SYSID_THISMAV 参数
--uav_connection 127.0.0.1:17171 MAVLink地址-- host:port 用于UDP，或用于USB的串行设备路径
--connection_type udpin udpin --服务器监听； udpout --服务器连接出去； usb --串行
--gradys_gs 没有 host:port Gradys地面站-- uav-api 每秒推送GPS位置
--scripts_path ~/uav_scripts 保存任务脚本的目录
--python_path python3 用于运行脚本的Python二进制文件
--simulated false 设置为 true 与ArduCopter SITL一起繁殖 uav-api
--ardupilot_path ~/ardupilot 本地ArduPilot存储库的路径（模拟模式）
--location AbraDF SITL的指定主场
--speedup 1 SITL仿真时间倍增器
--gs_connection [] 额外 host:port 解决SITL流遥测问题（例如任务规划器）
--log_console [] 将日志打印到控制台的组件： API, COPTER, GRADYS_GS
--log_path 无 写入所有组件日志组合的文件路径
--debug [] 组件名称与 --log_console 但在DEBUG冗长
--script_logs None 脚本stdout/stderr保存为带时间戳的目录 .log 文件

请参阅 uav-api 文档 有关端点级别的详细信息。

额外功能

Gradys地面站集成

集 --gradys_gs <host:port> 和 uav-api 每秒将车辆的GPS位置发布到Gradys GS：

uav-mcp --port 8000 --sysid 1 --gradys_gs 192.168.1.10:5000

使用任务规划器进行视觉反馈

在模拟模式下，使用 --gs_connection 将MAVLink遥测数据流式传输到任务规划器（或任何地面军事系统）：

uav-mcp --simulated true --ardupilot_path ~/ardupilot --sysid 1 --gs_connection 192.168.1.5:14550

相关 MCP