mavlink-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mavlink-mcp What can this drone do, and where is it right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mavlink-mcp
mavlink-mcp is a vendor-neutral UAV capability layer + Model Context Protocol server built on open standards. It connects AI agents (Claude Desktop, Cursor, VS Code, and any other MCP client) to drones that speak MAVLink — PX4 SITL, ArduPilot SITL, and Pixhawk-class autopilots — through MAVSDK (BSD-3-Clause). Instead of wrapping protocol messages, it exposes 8 flight capabilities (telemetry, flight mode, arm/disarm, takeoff, land, goto, mission, return-to-launch) behind one clean API with safety guardrails on by default.
It is the sister project of rosbridge-mcp (AI agents ↔ ROS 2 robots) and shares its philosophy: open protocols only, readonly-by-default guardrails, simulation-first, zero telemetry, MIT licensed.
Note on the name: "mavlink-mcp" is a provisional working name. "MAVLink" is a trademark of the Dronecode Foundation; the project name may be adjusted pending a review of their trademark policy before any public release.
Safety disclaimer: this project is built for simulation and research. Flying real aircraft with it is entirely at your own risk and responsibility, including compliance with your local aviation law (registration, flight permits, pilot licensing). See SECURITY.md.
Why a capability layer, not another SDK?
For AI agents, capabilities beat 400 SDK functions. An agent asks
get_capabilities("what can this drone do?"), gets back a small vocabulary of physical actions, and plans with it — no MAVLink knowledge needed on the model side.Vendor-neutral by construction. Capabilities are defined in physical quantities (degrees, meters, volts) from open specs — not copied from any proprietary SDK surface. The MAVSDK adapter is one implementation; a future ROS 2 adapter (reusing rosbridge-mcp) implements the same interface.
Guardrails are part of the API, not an afterthought. Readonly mode is the default, arming and takeoff require explicit operator-approved confirmation, and every commanded location is checked against an altitude ceiling and a soft geofence — before anything reaches the autopilot.
Related MCP server: ardupilot-mavlink-mcp
Architecture
+--------------------+ stdio (MCP) +----------------------------------+ MAVLink (UDP) +------------------+
| AI client | <-----------> | mavlink-mcp | <-------------> | PX4 / ArduPilot |
| (Claude, Cursor, | | MCP server | via | SITL or real FC |
| VS Code, ...) | | └─ capability layer + policy | MAVSDK | (Pixhawk-class) |
+--------------------+ | └─ MAVSDK adapter | (BSD-3) +------------------+
+----------------------------------+
Python scripts use the same capability layer directly (mavlink_mcp.Drone).The capability layer (Drone) owns all policy — readonly, confirmation, altitude, geofence. The adapter (MavsdkAdapter) only translates approved operations to MAVLink; it is the only module that imports mavsdk. New backends implement the same DroneAdapter interface and inherit both surfaces (MCP tools + Python library) and every guardrail for free.
Quick Start (60 seconds)
pip install git+https://github.com/hieutachi/mavlink-mcp.gitStart a PX4 SITL (see docs/simulator-quickstart.md — one Docker command), then add to your MCP client config:
{
"mcpServers": {
"mavlink": {
"command": "mavlink-mcp",
"env": { "MAVLINK_MCP_READONLY": "true" }
}
}
}Then ask your agent: "What can this drone do, and where is it right now?"
When you're ready to fly (in the simulator!), set MAVLINK_MCP_READONLY to "false".
Capabilities & tools
12 tools covering 8 capabilities. All tools return JSON; errors come back as {"error": "...", "guardrail": true} instead of raising, so the agent can read and react.
Tool | Capability | What it does | Mutating? |
| — | What the vehicle supports + active guardrails | no |
| Telemetry | Position, attitude, battery, GPS, mode, armed, in-air | no |
| FlightMode | Current flight mode (HOLD, MISSION, RTL, ...) | no |
| — | Endpoint, connection state, guardrail config | no |
| Arm/Disarm | Spin up motors | yes — requires |
| Arm/Disarm | Stop motors (on the ground) | yes |
| Takeoff | Climb to a target altitude | yes — requires |
| Land | Land at the current position | yes |
| FlightMode | Pause: stop and loiter in place | yes |
| ReturnToLaunch | Fly home and land | yes |
| Goto | Fly to one waypoint and loiter | yes — geofence + altitude checked |
| Mission | Upload a waypoint mission and start it | yes — every waypoint checked |
Example conversation
You: Check the drone and, if it's healthy, do a short patrol at 20 m.
Agent: (calls
get_capabilities— sees readonly is off, geofence 200 m; callsget_telemetry— GPSFIX_3D, 10 satellites, battery 100%) The drone is healthy. I need your approval to arm and take off — confirm?You: Confirmed, go ahead.
Agent: (calls
arm(confirm=true),takeoff(altitude_m=20, confirm=true), thenfly_missionwith 3 waypoints inside the geofence, monitorsget_telemetry, finishes withreturn_to_launch) Patrol complete — the drone is back at the launch point and disarmed.
Configuration
Environment variable | Default | Description |
|
| MAVLink endpoint (PX4 SITL's offboard port). With MAVSDK 2.x the older syntax |
|
| Reject every tool that can move the vehicle (see Safety) |
|
| Ceiling for takeoff/goto/mission altitudes, meters above launch. |
|
| Soft geofence radius around the home position, meters. |
Safety
Letting a language model command an aircraft is a real risk, so the guardrails are stricter than a typical SDK:
Readonly by default. Unlike most tools, you must explicitly opt in to flight with
MAVLINK_MCP_READONLY=false. In readonly mode all telemetry tools work; every mutating tool is rejected with a clear explanation.Two-step confirmation for the dangerous transitions.
armandtakeoffrequireconfirm=true, and the tool descriptions instruct the agent to obtain human approval first — an agent cannot legitimately take off in a single autonomous step.Soft geofence + altitude ceiling. Every commanded location (goto and each mission waypoint) is validated against
MAVLINK_MCP_GEOFENCE_RADIUS_Maround home andMAVLINK_MCP_MAX_ALTITUDE_Mbefore anything is sent to the autopilot.Safety actions stay friction-free.
land,hold, andreturn_to_launchnever require confirmation — de-escalation must always be cheap.
These checks are policy inside this process — not a substitute for the autopilot's own failsafes, a real geofence configured in PX4/ArduPilot, network isolation, or a human with an RC transmitter. Read SECURITY.md before considering real hardware, and treat real-world flights as requiring registration/permits under your local aviation law (e.g. Vietnam's UAV Decree 288/2025 requires registration and flight permits).
Python library
The same capability layer is importable for scripts and notebooks — see examples/patrol_sitl.py for a full takeoff → waypoint → land run against SITL:
from mavlink_mcp import Drone, GuardrailConfig
from mavlink_mcp.adapters.mavsdk_adapter import MavsdkAdapter
drone = Drone(MavsdkAdapter(), guardrails=GuardrailConfig(readonly=False))
snapshot = await drone.get_telemetry()
await drone.arm(confirm=True)
await drone.takeoff(20.0, confirm=True)Privacy & legal
No telemetry, no data collection. The only network connection this package opens is the MAVLink endpoint you configure (MAVLINK_MCP_URL). Vehicle data returned by tools goes exclusively to your MCP client.
License compliance. The core deliberately depends on MAVSDK-Python (BSD-3-Clause) and not on pymavlink (LGPL-3), keeping the dependency tree permissive under this project's MIT license. Direct dependencies: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). All code in this repository is original work written from public, open specifications (MAVLink protocol docs, MAVSDK docs) — no proprietary SDKs, no reverse engineering, no vendor EULAs accepted.
FAQ
Do I need a drone? No. MVP1 is simulation-first: everything works against PX4 SITL (one Docker command) and is designed to also work against ArduPilot SITL. See docs/simulator-quickstart.md.
Does it work with ArduPilot? The capability layer targets both PX4 and ArduPilot through MAVSDK. PX4 SITL is the primary tested target in MVP1; ArduPilot SITL compatibility notes are in the quickstart, and validating it in CI is a roadmap item.
Why not just use MAVSDK directly? If you're writing Python by hand, do! mavlink-mcp adds the layer MAVSDK doesn't have: an MCP tool surface for AI agents, a capability model with runtime discovery, and production guardrails (readonly, confirmation, geofence) enforced above the protocol.
The agent says no vehicle was discovered.
Check the SITL is running and sending MAVLink to the endpoint in MAVLINK_MCP_URL (PX4 SITL sends to UDP 14540 by default). The quickstart has a troubleshooting table.
Is my data sent anywhere? Only to your MCP client, which forwards it to whatever LLM you use — treat position data accordingly.
Roadmap
Staged plan in ROADMAP.md: MVP1 (this — capability layer + MCP server on SITL), MVP2 (real Pixhawk-class hardware, ROS 2 adapter reusing rosbridge-mcp, plugin/conformance system), MVP3 (community adapters, multi-vehicle, open-core services).
Contributing
Contributions are welcome — see CONTRIBUTING.md. Please sign off your commits (DCO). Note the clean-contribution rule: PRs must be based on public specs and documentation only.
License
MIT — see LICENSE. Dependency licenses are permissive and compatible: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). No GPL/LGPL/AGPL dependencies in the core.
Tóm tắt tiếng Việt
mavlink-mcp là lớp capability trung lập (vendor-neutral) cho UAV kèm MCP server, xây hoàn toàn trên chuẩn mở: kết nối AI agent (Claude Desktop, Cursor, VS Code...) với drone nói MAVLink (PX4/ArduPilot) qua thư viện MAVSDK (BSD-3). Đây là dự án chị em của rosbridge-mcp.
8 capability: telemetry (vị trí/tư thế/pin/GPS), flight mode, arm/disarm, takeoff, land, goto, mission, return-to-launch — 12 tool MCP.
An toàn mặc định: chế độ readonly bật sẵn (
MAVLINK_MCP_READONLYmặc địnhtrue); arm và takeoff cầnconfirm=truesau khi người vận hành đồng ý; geofence mềm + trần độ cao cấu hình được.Simulation-first: chạy với PX4 SITL (1 lệnh Docker) — xem docs/simulator-quickstart.md. Dự án dành cho mô phỏng/nghiên cứu; bay thật hoàn toàn do bạn tự chịu trách nhiệm, bao gồm đăng ký thiết bị và xin phép bay theo Luật Phòng không nhân dân 49/2024 và Nghị định 288/2025.
Tên "mavlink-mcp" là tên tạm — sẽ rà soát trademark policy của Dronecode trước khi công bố.
Available Tools
12 toolsarmA
Arm the vehicle (spin up motors). DANGEROUS on real hardware.
Rejected in readonly mode. Additionally requires confirm=true: ask the human operator for approval first — never set confirm=true on your own initiative. Preflight: check get_telemetry (GPS fix, battery) before arming. Returns {"armed": true} or {"error": ...}.
Inputs: confirm. Returns: object
disarmA
Disarm the vehicle (stop motors). Autopilots reject this in flight.
Rejected in readonly mode. Returns {"disarmed": true} or {"error": ...}.
Inputs: no named parameters. Returns: object
fly_missionA
Upload a waypoint mission and start flying it. The vehicle must be armed and flying (or the autopilot will take off per its mission config).
Args: waypoints: List of {"latitude_deg", "longitude_deg", "relative_altitude_m", "speed_m_s"?} objects, flown in order. Every waypoint is validated against the altitude ceiling and the soft geofence before anything is uploaded.
Rejected in readonly mode. Returns {"mission_started": true, "waypoint_count": N}. Use hold to pause or return_to_launch to abort; poll get_flight_mode — mode leaves MISSION when the mission ends.
Inputs: waypoints (required). Returns: object
get_capabilitiesA
Discover what this vehicle can do and which guardrails are active.
Takes no arguments; does not require a live vehicle. Call this first. Returns {"adapter", "capabilities": ["telemetry", "arm_disarm", ...], "guardrails": {"readonly", "max_altitude_m", "geofence_radius_m"}, "connected"}. Plan only with listed capabilities; if "readonly" is true, every tool that can move the vehicle will be rejected.
Inputs: no named parameters. Returns: object
get_connection_statusA
Report the MAVLink endpoint, connection state, and guardrail config.
Takes no arguments. The connection is opened lazily, so "connected" is false until another tool has been used. Check this first when other tools report errors.
Inputs: no named parameters. Returns: object
get_flight_modeA
Report the current flight mode (e.g. HOLD, TAKEOFF, MISSION, RTL).
Takes no arguments. Read-only. Returns {"flight_mode": "HOLD"}.
Inputs: no named parameters. Returns: object
get_telemetryA
Read one snapshot of the vehicle's telemetry. Read-only.
Takes no arguments. Returns {"position": {latitude_deg, longitude_deg, absolute_altitude_m, relative_altitude_m}, "attitude": {roll_deg, pitch_deg, yaw_deg}, "battery": {voltage_v, remaining_percent}, "gps": {num_satellites, fix_type}, "flight_mode", "armed", "in_air"}. Fields the vehicle did not report within a few seconds are null. Always check telemetry before commanding motion.
Inputs: no named parameters. Returns: object
goto_locationA
Fly to a single waypoint and loiter there. The vehicle must be flying already (armed + taken off).
Args: latitude_deg: Target latitude (WGS84). longitude_deg: Target longitude (WGS84). relative_altitude_m: Target altitude above the launch point, in meters. Checked against the altitude ceiling. yaw_deg: Heading at the target, 0 = north (default 0).
Rejected in readonly mode. The target is also checked against the soft geofence around home (MAVLINK_MCP_GEOFENCE_RADIUS_M, default 200 m). Returns {"goto_started": true, "target": {...}} — travel is asynchronous; poll get_telemetry to track progress.
Inputs: latitude_deg (required), longitude_deg (required), relative_altitude_m (required), yaw_deg. Returns: object
holdA
Pause: stop and loiter at the current position (HOLD mode).
Rejected in readonly mode. Use this to interrupt a goto or mission safely. Returns {"holding": true}.
Inputs: no named parameters. Returns: object
landA
Land at the current position.
Rejected in readonly mode (no confirmation needed — landing makes the vehicle safer). Returns {"landing_started": true}; poll get_telemetry until "in_air" is false.
Inputs: no named parameters. Returns: object
return_to_launchA
Fly back to the launch point and land there (RTL).
Rejected in readonly mode (no confirmation needed — RTL is a recovery action). Returns {"rtl_started": true}; poll get_telemetry until "in_air" is false.
Inputs: no named parameters. Returns: object
takeoffA
Take off vertically to altitude_m meters above the launch point.
Rejected in readonly mode. Additionally requires confirm=true after human operator approval — never set it on your own initiative. The vehicle must be armed first (call arm). Altitude is validated against the configured ceiling (MAVLINK_MCP_MAX_ALTITUDE_M, default 50 m).
Returns {"takeoff_started": true, "target_altitude_m": ...} — takeoff is asynchronous; poll get_telemetry to watch the climb.
Inputs: confirm, altitude_m. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct purpose: read operations (get_flight_mode, get_capabilities, get_telemetry, get_connection_status), safety actions (arm, disarm), and navigation commands (takeoff, land, hold, return_to_launch, goto_location, fly_mission). No overlap or ambiguity.
Most tools use a consistent verb_noun pattern with snake_case (e.g., get_flight_mode, get_telemetry). Action verbs are single words (arm, disarm, takeoff, land, hold) except return_to_launch and goto_location, which are phrases. The pattern is clear and predictable, with only minor deviation.
12 tools is well-scoped for a drone control server. It covers essential read capabilities, safety, and navigation without being excessive. Each tool has a clear role and contributes to a complete workflow.
The toolset covers core drone operations: reading state, arming, disarming, takeoff, landing, holding, returning, going to a location, and flying missions. Minor gaps exist, such as no direct parameter setting or mode change tool, but the core workflows are fully supported and the guardrails are well-integrated.
Maintenance
Related MCP Connectors
Connect Claude, Cursor, Codex, and other AI tools to your robotics mission data.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Your AI Agent's Infrastructure Layer. Connect Claude, Copilot, Codex, or ChatGPT to 200+ managed open source services. Start databases, pipelines, and applications through natural language.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables natural language control of ArduPilot drones via MAVLink, supporting arm, takeoff, mode changes, and mission uploads.9GPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with an ArduPilot vehicle in real-time via MAVLink, including reading state, inspecting and changing parameters, switching flight modes, diagnosing arming failures, and gated arming/disarming.58 PyPI4MIT
- AlicenseBqualityCmaintenanceEnables AI assistants to control Betaflight flight controllers over serial via MSP and CLI, providing real-time sensor reads, full CLI access, and auto-generated variable tools for configuration and tuning.10026 npm3AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to read live drone status, telemetry, and parameters, and to control drone operations with scoped permissions, confirmation steps, and audit trails.MIT