mavlink-mcp

mavlink-mcp는 벤더 중립적인 UAV 기능 계층 + 오픈 표준 기반의 Model Context Protocol 서버입니다. AI 에이전트(Claude Desktop, Cursor, VS Code 및 기타 MCP 클라이언트)를 MAVSDK(BSD-3-Clause)를 통해 MAVLink를 사용하는 드론(PX4 SITL, ArduPilot SITL, Pixhawk급 자동조종장치)에 연결합니다. 프로토콜 메시지를 감싸는 대신, 8가지 비행 기능(텔레메트리, 비행 모드, 시동/시동 해제, 이륙, 착륙, 이동, 임무, 귀환)을 안전 보호 장치가 기본으로 활성화된 상태로 하나의 깔끔한 API 뒤에 노출합니다.

이 프로젝트는 rosbridge-mcp(AI 에이전트 ↔ ROS 2 로봇)의 자매 프로젝트로, 동일한 철학을 공유합니다: 오픈 프로토콜만 사용, 읽기 전용 기본 보호 장치, 시뮬레이션 우선, 제로 텔레메트리, MIT 라이선스.

이름에 대한 참고: "mavlink-mcp"는 임시 작업 이름입니다. "MAVLink"는 Dronecode Foundation의 상표입니다. 프로젝트 이름은 공개 출시 전에 상표 정책 검토 후 조정될 수 있습니다.

안전 고지: 이 프로젝트는 시뮬레이션 및 연구용으로 제작되었습니다. 실제 항공기를 비행하는 것은 전적으로 사용자의 책임이며, 해당 지역 항공 법률(등록, 비행 허가, 조종사 면허)을 준수해야 합니다. SECURITY.md를 참조하세요.

기능 계층인 이유, 또 다른 SDK가 아닌 이유?

• AI 에이전트에게는 400개의 SDK 함수보다 기능이 낫습니다. 에이전트가 get_capabilities("이 드론이 무엇을 할 수 있나요?")를 요청하면, 소수의 물리적 동작 어휘를 반환받고 이를 사용하여 계획을 세웁니다. 모델 측에서 MAVLink 지식이 필요 없습니다.

• 구조적으로 벤더 중립적입니다. 기능은 물리량(도, 미터, 볼트)으로 정의되며, 이는 오픈 사양을 기반으로 합니다. 독점 SDK 표면을 복사하지 않습니다. MAVSDK 어댑터는 하나의 구현체이며, 향후 ROS 2 어댑터(rosbridge-mcp 재사용)는 동일한 인터페이스를 구현합니다.

• 보호 장치는 API의 일부이며, 나중에 추가된 것이 아닙니다. 읽기 전용 모드가 기본값이며, 시동 및 이륙은 명시적인 운영자 승인 확인이 필요하며, 모든 명령 위치는 자동조종장치에 도달하기 전에 고도 상한 및 소프트 지오펜스에 대해 확인됩니다.

Related MCP server: ArduPilot MCP Server Sandbox

아키텍처

+--------------------+  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).

기능 계층(Drone)은 모든 정책(읽기 전용, 확인, 고도, 지오펜스)을 소유합니다. 어댑터(MavsdkAdapter)는 승인된 작업만 MAVLink로 변환합니다. 이는 mavsdk를 임포트하는 유일한 모듈입니다. 새로운 백엔드는 동일한 DroneAdapter 인터페이스를 구현하며, 두 표면(MCP 도구 + Python 라이브러리)과 모든 보호 장치를 무료로 상속받습니다.

빠른 시작 (60초)

pip install git+https://github.com/hieutachi/mavlink-mcp.git

PX4 SITL을 시작하고(docs/simulator-quickstart.md 참조 - Docker 명령어 하나), MCP 클라이언트 구성에 추가합니다:

{
  "mcpServers": {
    "mavlink": {
      "command": "mavlink-mcp",
      "env": { "MAVLINK_MCP_READONLY": "true" }
    }
  }
}

그런 다음 에이전트에게 물어보세요: "이 드론이 무엇을 할 수 있고, 지금 어디에 있나요?"

비행할 준비가 되면(시뮬레이터에서!) MAVLINK_MCP_READONLY를 "false"로 설정하세요.

기능 및 도구

8가지 기능을 다루는 12개의 도구. 모든 도구는 JSON을 반환하며, 오류는 발생시키지 않고 {"error": "...", "guardrail": true}로 반환되어 에이전트가 읽고 대응할 수 있습니다.

대화 예시

사용자: 드론을 확인하고, 상태가 좋으면 20m에서 짧은 순찰을 수행하세요.

에이전트: (get_capabilities 호출 — 읽기 전용이 꺼져 있고, 지오펜스 200m 확인; get_telemetry 호출 — GPS FIX_3D, 위성 10개, 배터리 100%) 드론 상태가 양호합니다. 시동 및 이륙을 위해 승인이 필요합니다. 확인하시겠습니까?

사용자: 확인했습니다. 진행하세요.

에이전트: (arm(confirm=true) 호출, takeoff(altitude_m=20, confirm=true) 호출, 지오펜스 내 3개 웨이포인트로 fly_mission 호출, get_telemetry 모니터링, return_to_launch로 마무리) 순찰 완료 — 드론이 이륙 지점으로 돌아와 시동이 해제되었습니다.

구성

안전

언어 모델이 항공기를 지휘하도록 하는 것은 실제 위험이므로, 보호 장치는 일반 SDK보다 더 엄격합니다:

1. 기본 읽기 전용. 대부분의 도구와 달리, 비행을 위해 MAVLINK_MCP_READONLY=false로 명시적으로 옵트인해야 합니다. 읽기 전용 모드에서는 모든 텔레메트리 도구가 작동합니다. 모든 변경 도구는 명확한 설명과 함께 거부됩니다.

2. 위험한 전환에는 2단계 확인. arm 및 takeoff는 confirm=true가 필요하며, 도구 설명은 에이전트가 먼저 사람의 승인을 받도록 지시합니다. 에이전트가 단일 자율 단계에서 정당하게 이륙할 수 없습니다.

3. 소프트 지오펜스 + 고도 상한. 모든 명령 위치(이동 및 각 임무 웨이포인트)는 자동조종장치로 전송되기 전에 집 주변 MAVLINK_MCP_GEOFENCE_RADIUS_M 및 MAVLINK_MCP_MAX_ALTITUDE_M에 대해 검증됩니다.

4. 안전 조치는 장애물 없이 유지. land, hold, return_to_launch는 절대 확인이 필요하지 않습니다. 위험 완화는 항상 저렴해야 합니다.

이러한 검사는 이 프로세스 내의 정책입니다. 자동조종장치 자체의 안전 장치, PX4/ArduPilot에 구성된 실제 지오펜스, 네트워크 격리 또는 RC 송신기를 가진 사람을 대체하지 않습니다. 실제 하드웨어를 고려하기 전에 SECURITY.md를 읽고, 실제 비행은 해당 지역 항공 법률(예: 베트남의 무인기 법령 288/2025는 등록 및 비행 허가 필요)에 따라 등록/허가가 필요함을 인식하세요.

Python 라이브러리

동일한 기능 계층을 스크립트 및 노트북에서 임포트할 수 있습니다. SITL에 대한 전체 이륙 → 웨이포인트 → 착륙 실행 예제는 examples/patrol_sitl.py를 참조하세요:

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)

개인정보 보호 및 법적 고지

텔레메트리 없음, 데이터 수집 없음. 이 패키지가 여는 유일한 네트워크 연결은 사용자가 구성한 MAVLink 엔드포인트(MAVLINK_MCP_URL)입니다. 도구가 반환하는 차량 데이터는 오직 MCP 클라이언트로만 전송됩니다.

라이선스 준수. 핵심은 의도적으로 **MAVSDK-Python (BSD-3-Clause)**에 의존하며, pymavlink(LGPL-3)에는 의존하지 않아 이 프로젝트의 MIT 라이선스 하에 허용적인 의존성 트리를 유지합니다. 직접 의존성: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). 이 저장소의 모든 코드는 공개된 오픈 사양(MAVLink 프로토콜 문서, MAVSDK 문서)에서 작성된 독창적인 작업입니다. 독점 SDK, 리버스 엔지니어링, 공급업체 EULA 수락은 없습니다.

FAQ

드론이 필요한가요? 아니요. MVP1은 시뮬레이션 우선입니다: 모든 것이 PX4 SITL( Docker 명령어 하나)에서 작동하며, ArduPilot SITL에서도 작동하도록 설계되었습니다. docs/simulator-quickstart.md를 참조하세요.

ArduPilot에서도 작동하나요? 기능 계층은 MAVSDK를 통해 PX4와 ArduPilot을 모두 지원합니다. MVP1에서 PX4 SITL이 기본 테스트 대상이며, ArduPilot SITL 호환성 참고 사항은 빠른 시작 가이드에 있으며, CI에서 검증하는 것은 로드맵 항목입니다.

왜 MAVSDK를 직접 사용하지 않나요? Python을 직접 작성하는 경우 그렇게 하세요! mavlink-mcp는 MAVSDK가 제공하지 않는 계층을 추가합니다: AI 에이전트를 위한 MCP 도구 표면, 런타임 검색이 가능한 기능 모델, 프로토콜 위에서 시행되는 프로덕션 보호 장치(읽기 전용, 확인, 지오펜스).

에이전트가 차량을 발견하지 못했다고 합니다. SITL이 실행 중이고 MAVLINK_MCP_URL의 엔드포인트로 MAVLink를 보내고 있는지 확인하세요(PX4 SITL은 기본적으로 UDP 14540으로 전송). 빠른 시작 가이드에 문제 해결 표가 있습니다.

내 데이터가 어디로 전송되나요? MCP 클라이언트로만 전송되며, 해당 클라이언트는 사용자가 사용하는 모든 LLM으로 전달합니다. 위치 데이터를 적절히 처리하세요.

로드맵

단계별 계획은 ROADMAP.md에 있습니다: MVP1 (현재 - 기능 계층 + SITL의 MCP 서버), MVP2 (실제 Pixhawk급 하드웨어, rosbridge-mcp 재사용하는 ROS 2 어댑터, 플러그인/적합성 시스템), MVP3 (커뮤니티 어댑터, 다중 차량, 오픈 코어 서비스).

기여

기여를 환영합니다. CONTRIBUTING.md를 참조하세요. 커밋에 서명(DCO)해 주세요. 깨끗한 기여 규칙에 유의하세요: PR은 공개 사양 및 문서만 기반으로 해야 합니다.

라이선스

MIT — LICENSE를 참조하세요. 의존성 라이선스는 허용적이며 호환됩니다: mavsdk (BSD-3-Clause), fastmcp (Apache-2.0). 핵심에 GPL/LGPL/AGPL 의존성은 없습니다.

베트남어 요약

mavlink-mcp는 UAV를 위한 벤더 중립적인 기능 계층과 MCP 서버로, 전적으로 오픈 표준 위에 구축되었습니다: MAVSDK(BSD-3) 라이브러리를 통해 MAVLink를 사용하는 드론(PX4/ArduPilot)에 AI 에이전트(Claude Desktop, Cursor, VS Code 등)를 연결합니다. 이 프로젝트는 rosbridge-mcp의 자매 프로젝트입니다.

• 8가지 기능: 텔레메트리(위치/자세/배터리/GPS), 비행 모드, arm/disarm, 이륙, 착륙, 이동, 임무, 귀환 — 12개 도구 MCP.

• 기본 안전: 읽기 전용 모드 기본 활성화 (MAVLINK_MCP_READONLY 기본값 true); arm 및 이륙은 운영자가 동의한 후 confirm=true 필요; 소프트 지오펜스 + 구성 가능한 고도 제한.

• 시뮬레이션 우선: PX4 SITL로 실행 (Docker 명령 1개) — docs/simulator-quickstart.md 참조. 이 프로젝트는 시뮬레이션/연구용입니다. 실제 비행은 전적으로 본인 책임이며, 장비 등록 및 인민방공법 49/2024 및 시행령 288/2025에 따른 비행 허가 신청을 포함합니다.

• "mavlink-mcp"라는 이름은 임시 명칭입니다 — 공개 전에 Dronecode의 상표 정책을 검토할 예정입니다.