ardupilot-mavlink-mcp

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

!CI  !License: MIT !Python !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 client

Claude Code:

claude mcp add ardupilot -- ardupilot-mavlink-mcp --connect tcp:127.0.0.1:5760

Claude Desktop / any mcpServers config:

{
  "mcpServers": {
    "ardupilot": {
      "command": "ardupilot-mavlink-mcp",
      "args": ["--connect", "tcp:127.0.0.1:5760"]
    }
  }
}

Connection strings are pymavlink syntax: tcp:127.0.0.1:5760 (SITL), udp:127.0.0.1:14550, serial:/dev/ttyACM0:115200.

Tools

| Tool | Kind | What it does | | --- | --- | --- | | ardupilot_connect | — | Connect to a vehicle. Default is local SITL. | | ardupilot_vehicle_state | read | Mode, armed, GPS, battery, attitude, position — from cache. | | ardupilot_recent_statustext | read | Recent STATUSTEXT/prearm messages. Read this to see why arming failed. | | ardupilot_get_param | read | Read one parameter. | | ardupilot_set_param | write | Set a parameter, confirmed via echoed PARAM_VALUE. | | ardupilot_list_params | read | List params, optional glob (ATC_RAT_*). | | ardupilot_set_mode | write | Send a request to set flight mode by name. | | ardupilot_arm / ardupilot_disarm | write | Gated. Confirmed via COMMAND_ACK. |

Write tools are gated and carry the MCP destructiveHint. Live telemetry is also exposed as the resource ardupilot://telemetry.

Supported vehicles

| Vehicle | Firmware | Status | | --- | --- | --- | | ArduCopter | 4.5 | ✓ validated on SITL | | ArduRover (UGV/USV) | 4.x | ~ mode map present, not yet validated | | ArduPlane | 4.x | ~ mode map present, not yet validated | | ArduSub | 4.x | ~ untested |

MAVLink2 is assumed. Not flown on hardware — SITL only so far.

Safety model

1. Actuation tools are OFF by default. Enable with --enable-actuation.
2. Even enabled, actuation on a real link (serial or non-loopback network) is refused unless --allow-real-vehicle is also set.
3. Link classification fails safe: anything not clearly loopback is treated as a real vehicle.
4. arm, disarm, set_param, and set_mode all pass through this gate before sending.
5. Arming has no force-arm option, and set_param rejects ARMING_CHECK writes (case-insensitive) on every link, even when both actuation flags are enabled.

Status

Working: reads plus gated parameter writes, mode changes, and arm/disarm against ArduCopter SITL. Validated three ways — unit tests (Python 3.10–3.12), a real-MAVLink-wire check (scripts/wire_check.py), and a live ArduPilot SITL run (scripts/sitl_check.py).

Open targets: validate Rover/Plane/Sub; mission upload/download and guided flight (takeoff/goto/land) are deferred — mission protocol is a stateful handshake and guided commands are fly-away risk. See ROADMAP.md.

Develop

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            # offline real-wire check, no SITL needed

License

MIT — Kyle Adomavicius