ardupilot-mcp

An MCP server that lets an AI agent talk to an ArduPilot vehicle over MAVLink. Read state, inspect and change parameters, switch modes, read prearm failures, and (gated) arm or disarm. SITL-first.

Install: pipx install ardupilot-mavlink-mcp

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

[!WARNING] This tool can ARM and command a real aircraft. A bad command can spin props or fly a vehicle away. Defaults are built to stop that: actuation is OFF unless you pass --enable-actuation, and even then it refuses a real (non-loopback) link unless you also pass --allow-real-vehicle. Develop against SITL. On hardware, bench-test with props off first. No warranty — you own the outcome.

Why

Most ArduPilot tooling for LLMs targets post-flight log analysis. This one drives the live link: connect to a running vehicle, read its state and params, change modes, and diagnose why it won't arm — in the moment, not after landing. The useful case: point an agent at a vehicle that won't arm, have it read the params and the prearm STATUSTEXT, and tell you why, instead of you squinting at a GCS message log. The arm tool reports the real COMMAND_ACK result and hands back the prearm reasons on refusal; it never force-arms.

Architecture

  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 is an async stream; MCP tools are synchronous. One background thread owns the link and is the only reader — it caches the latest message of each type and routes PARAM_VALUE into a param store. Tool calls read from those caches (params block until the data arrives). No two threads ever call recv_match.

What it does

• Reads vehicle state from cache, instantly. Mode, armed, GPS fix and sats, battery, attitude, position — served from cached telemetry, no blocking on the link.
• Diagnoses a no-arm. ardupilot_arm returns the COMMAND_ACK result and, on refusal, the prearm STATUSTEXT (e.g. AHRS: waiting for home, Accels inconsistent). Safety checks are respected — no ARMING_CHECK=0, no force-arm magic number.
• Gets and sets parameters on the real param table, with set confirmed by the echoed PARAM_VALUE.
• Switches flight modes by name, mapped per vehicle type (Copter/Rover/Plane/Sub) — not hardcoded numbers.

Quick start (SITL)

You need an ArduPilot SITL instance. From an ardupilot checkout:

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

Install and run the server (read-only by default):

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

To allow parameter writes, mode changes, and arm/disarm against SITL, add --enable-actuation.

Use with an MCP

... View full README on GitHub