ArduPilot MAVLink

Name: ArduPilot MAVLink
Author: rmeadomavic

@rmeadomavicMCP server · External

Live ArduPilot control over MAVLink: state, params, modes, prearm diagnosis, gated arm. SITL-first.

Aviationv0.1.0MITPython

Freeno charge per call

How to install

Runs on your machine from its package; the steps are below.

What it does

Reads
Writes
High impact

At most: moves money, runs code or commands, deletes data, or sends messages for you.

What it costs

Free

Odel charges nothing per call. The publisher may charge for its own service.

Runs locally over stdio

This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).

PyPIardupilot-mavlink-mcpv0.1.0

Run

uvx ardupilot-mavlink-mcp

MCP client config

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

README5 min readView on GitHub

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:

bash

# 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):

bash

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:

bash

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

Claude Desktop / any mcpServers config:

json

{
  "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

Actuation tools are OFF by default. Enable with --enable-actuation.
Even enabled, actuation on a real link (serial or non-loopback network) is refused unless --allow-real-vehicle is also set.
Link classification fails safe: anything not clearly loopback is treated as a real vehicle.
arm, disarm, set_param, and set_mode all pass through this gate before sending.
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

bash

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

Similar modules

Browse Aviation