mobile-mcp github 분석

모바일 앱 테스트 추천 도구

GitHub - mobile-next/mobile-mcp: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simu

 

1. 구조를 먼저 보면 이해가 쉽습니다

Codex / Claude Code / Gemini / Cursor
                 │
                 │ MCP
                 ▼
        ┌─────────────────┐
        │   mobile-mcp    │
        │  MCP Tool Layer │
        └────────┬────────┘
                 │
                 ▼
        ┌─────────────────┐
        │    mobilecli    │
        │ Device abstraction
        └────────┬────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
 Android Device Kit    iOS Device Kit
        │                 │
        ▼                 ▼
Android 실기기/Emulator  iPhone/Simulator

실제 코드에서도 mobile-mcp가 MobileDevice라는 공통 Robot 인터페이스를 만들고, 대부분의 작업을 mobilecli 명령으로 전달합니다. 예를 들어 화면 탭은 결국 mobilecli io tap, 텍스트 입력은 io text, UI 분석은 dump ui, 앱 실행은 apps launch 형태로 내려갑니다. GitHub

즉 역할을 구분하면:

mobile-mcp = AI가 이해하기 쉬운 MCP API
mobilecli = 실제 디바이스 제어 엔진

이라고 보면 됩니다.

---

2. 가장 중요한 특징: 스크린샷만 보고 누르는 방식이 아닙니다

이 부분이 이 프로젝트의 강점입니다.

AI 모바일 자동화라고 하면 보통:

스크린샷
  ↓
Vision AI
  ↓
"로그인 버튼이 대충 여기 있네"
  ↓
x=421, y=733 터치

방식을 생각하기 쉬운데 Mobile MCP는 우선 Accessibility/UI hierarchy를 읽습니다.

예를 들어 AI에게 이런 구조가 전달됩니다.

@e1 Button "로그인"
@e2 TextField "이메일"
@e3 TextField "비밀번호"
@e4 Button "회원가입"

그리고 AI는:

tap @e2
type "test@example.com"

tap @e3
type "1234"

tap @e1

처럼 조작합니다.

실제 최신 코드에서 mobile_list_elements_on_screen이 ref, 위치, 레이블을 돌려주며, mobile_click_on_screen_at_coordinates에 @e5 같은 ref를 직접 전달할 수 있습니다. GitHub

이 방식의 장점은 큽니다.

Vision 기반
화면 해석 → 좌표 추정 → 클릭
       ↓
 느림 / 토큰 많이 사용 / 오차 가능

Mobile MCP
Accessibility Tree → @ref → 클릭
       ↓
 빠름 / 저렴 / 비교적 안정적

스크린샷은 UI 트리에 잡히지 않는 Canvas, 게임 UI, 이미지 버튼, 시각적 품질 확인 등에 보조적으로 씁니다. 프로젝트가 제공하는 mobile-automation Skill도 UI tree를 먼저 사용하고 screenshot은 fallback으로 사용하도록 명시하고 있습니다. GitHub

---

3. 실제로 AI가 할 수 있는 것

현재 도구가 상당히 많습니다.

분야가능 작업

Device	디바이스 목록
Screen	해상도 확인
UI	화면 요소 읽기
Touch	Tap / Double Tap / Long Press
Gesture	Swipe
Keyboard	텍스트 입력
Button	Home / Back / Enter / Volume
App	앱 목록
App	설치 / 삭제
App	실행 / 종료
Browser	URL 열기
Screenshot	캡처
Recording	화면 녹화
Orientation	가로/세로 변경
GPS	가상 위치 설정
Clipboard	클립보드 읽기/쓰기
Debug	logcat / iOS unified log
Debug	Crash report 조회
Cloud	원격 실기기 할당

README 기준으로 iOS Simulator, iOS 실기기, Android Emulator, Android 실기기를 지원합니다. GitHub

특히 개발 테스트에서는 로그와 Crash report까지 AI가 읽을 수 있다는 것이 중요합니다. mobile_get_device_logs, mobile_list_crashes, mobile_get_crash가 실제 MCP Tool로 구현돼 있습니다. GitHub

그래서 단순한 UI 자동화보다 훨씬 재미있는 게 가능합니다.

AI에게:

"앱을 실행하고
회원가입 → 로그인 → 프로필 수정까지 테스트해.

오류가 발생하면 로그를 확인하고
원인을 찾아서 코드도 수정해."

같은 작업이 가능합니다.

---

4. 이것이 Codex와 붙으면 꽤 강력합니다

예를 들어 Android 앱 개발을 한다고 하면:

                Codex
                  │
        ┌─────────┴─────────┐
        │                   │
        ▼                   ▼
   프로젝트 소스        Mobile MCP
        │                   │
        ▼                   ▼
     코드 수정         Android Emulator
        │                   │
        └─────────┬─────────┘
                  ▼
               Build
                  ↓
             APK 설치
                  ↓
             앱 실행
                  ↓
             UI 테스트
                  ↓
         Screenshot / Logs
                  ↓
            문제 발견
                  ↓
             코드 수정
                  ↓
              재테스트

즉 코드 작성 → 앱 실행 → 실제 조작 → 검증 → 버그 수정 루프를 AI 하나가 돌릴 수 있습니다.

이게 이 레포의 가장 큰 가치입니다.

---

5. Batch Command도 꽤 중요합니다

초기 모바일 에이전트의 문제는 MCP 호출을 너무 많이 한다는 것입니다.

예:

tap
→ MCP 왕복

type
→ MCP 왕복

tap
→ MCP 왕복

type
→ MCP 왕복

최신 Mobile MCP에는 mobile_batch_commands가 들어갔습니다.

[
 tap email,
 type email,
 tap password,
 type password,
 tap login
]

을 한 번에 처리할 수 있습니다.

코드에서도 여러 tool callback을 순서대로 실행하고 마지막에 UI element를 다시 가져올 수도 있도록 구현돼 있습니다. GitHub

2026년 9월 업데이트에는 background daemon도 추가돼 device connection을 매번 다시 만드는 비용을 줄였습니다. GitHub

그래서 예전 버전에 비해서 현재 구조가 Agent automation용으로 상당히 많이 개선된 상태입니다.

---

6. Appium과는 성격이 조금 다릅니다

둘의 차이를 이렇게 생각하면 됩니다.

AppiumMobile MCP

대상	테스트 코드	AI Agent
작성 방식	테스트 스크립트	자연어
주요 사용자	QA/개발자	AI Agent
Android/iOS	지원	지원
UI Tree	지원	지원
자연어 작업	기본 X	핵심
MCP	X	핵심
exploratory testing	코드 작성 필요	매우 편함

예를 들어 Appium에서는 보통:

await driver.$('~Login').click()

같은 테스트 코드를 직접 만듭니다.

Mobile MCP에서는:

로그인 앱을 열어서
회원가입 기능을 테스트해줘.

하면 LLM이 Tool을 선택합니다.

그래서 Appium 대체제라기보다는 Agent용 상위 계층에 가깝습니다.

---

7. 그리고 Mobilewright와도 역할이 다릅니다

Mobile Next 팀은 별도로 mobilewright도 만들고 있습니다.

공식 README의 표현이 꽤 정확합니다.

Mobile MCP
AI가 앱을 탐색하고 테스트

       ↓

mobilewright
탐색 결과를 deterministic test로 고정

즉:

Agent exploratory testing
      │
      ▼
Mobile MCP
      │
테스트 시나리오 발견
      ▼
mobilewright
      │
고정된 자동화 테스트
      ▼
CI/CD

식으로 쓰려는 전략입니다. GitHub

Playwright와 비유하면:

Mobilewright = Playwright의 모바일 버전

에 가깝고,

Mobile MCP = AI Agent가 Mobilewright/Device를 자연어로 조종하도록 해주는 인터페이스

에 가깝습니다.

---

8. 설치도 상당히 단순합니다

Node 20+가 필요합니다. GitHub

Codex라면 공식 문서는 다음과 같은 설치를 안내합니다.

codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"

또는 ~/.codex/config.toml:

[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]

Claude Code:

claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest

그 다음:

list available devices

라고 하면 됩니다. npm의 현재 배포 버전은 1.0.5로 표시되고 있습니다. NPM

---

9. Android에서는 이런 흐름이 됩니다

Android Studio Emulator가 있다고 해보겠습니다.

Android Emulator 실행

        ↓

adb devices

        ↓

mobile-mcp 실행

        ↓

Codex:

"사용 가능한 디바이스 찾아줘"

        ↓

mobile_list_available_devices

        ↓

emulator-5554

        ↓

"내 APK를 설치해"

        ↓

mobile_install_app

        ↓

"앱 실행"

        ↓

mobile_launch_app

        ↓

"회원가입 테스트"

        ↓

mobile_list_elements_on_screen
       ↓
tap / type / swipe
       ↓
UI 확인

실제 앱 테스트 환경을 AI에게 붙이기에는 꽤 이상적인 구조입니다.

---

10. 화면 디자인 테스트에도 쓸 수 있습니다

예를 들어:

Android 앱을 실행해.

Pixel 9 환경에서 다음을 검사해.

1. 로그인 화면
2. 회원가입 화면
3. 홈 화면
4. 설정 화면

화면마다 screenshot을 저장하고
텍스트 잘림,
버튼 겹침,
화면 밖 요소,
스크롤 문제를 찾아줘.

같은 테스트가 가능합니다.

스크린샷은 기본적으로 AI에 너무 큰 이미지가 들어가지 않도록 리사이즈되고, 실제 화면 좌표로 환산할 수 있는 mapping 정보까지 함께 반환합니다. GitHub

---

11. 실제 실기기도 됩니다

공식 지원표상:

Mac
 ├─ iOS Simulator
 ├─ iPhone
 ├─ Android Emulator
 └─ Android Phone

전부 대상입니다. GitHub

2026년 9월 들어 구조가 상당히 바뀌었습니다. 예전 iOS 실기기는 WebDriverAgent + go-ios 의존성이 컸는데, 최신 roadmap에서는 자체 iOS Device Kit으로 교체하고 go-ios 의존성을 제거했다고 명시합니다. Android도 Device Kit을 바이너리에 내장하는 방향으로 변경됐습니다. GitHub

그래서 인터넷에 검색하면 보이는 예전 WebDriverAgent 설치 → go-ios tunnel 문서는 현재 구현과 일부 차이가 있을 수 있습니다. 실제 Wiki에도 아직 과거 WDA 절차가 남아 있어서 이 부분은 README/최신 changelog를 우선 보는 편이 좋습니다. GitHub

---

12. 네트워크 MCP 서버로도 만들 수 있습니다

이것도 꽤 중요한 기능입니다.

기본은:

Codex
  │ stdio
  ▼
Mobile MCP

인데 이제:

npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000

으로 띄우면:

노트북 A
Codex
   │
   │ HTTP
   ▼
192.168.0.10:3000/mcp
   │
노트북 B
Mobile MCP
   │
Android Device

같은 구성도 가능합니다.

Streamable HTTP를 지원하며 Bearer token 인증도 있습니다. NPM

다만 이건 MCP Client ↔ MCP Server의 네트워크 연결입니다.

Codex --Wi-Fi/LAN--> Mobile MCP

는 가능하지만,

Mobile MCP --Wi-Fi--> Android Phone

을 자체적으로 완전히 해결해주는 기능과는 별개입니다. 실제 GitHub에도 Android IP 연결 지원 요청이 아직 open issue로 남아 있습니다. GitHub

---

13. 아직 부족한 부분도 있습니다

Roadmap에 올라가 있는 기능을 보면 현재 경계가 명확합니다.

아직 계획 단계인 것들:

• Device 파일 push/pull
• App launch argument
• Pinch zoom
• WebView
• Browser 정식 제어
• Device settings
• 앱 storage clear 등이 있습니다. GitHub

Flutter 지원은 약간 애매합니다. changelog에는 mobilecli 레벨에서 Flutter UI dump가 추가됐다고 되어 있지만, roadmap에는 여전히 Flutter UI support가 Planned로 남아 있습니다. 즉 하부 구현은 진행됐지만 전체 MCP 경험이 완성됐다고 보기는 아직 이른 상태로 보입니다. GitHub

---

14. 현재 실제 이슈도 몇 개 있습니다

활발히 개발되는 프로젝트라 아직 edge case가 있습니다.

현재 open issue에는:

• Landscape일 때 tap 좌표 힌트 문제
• mobilecli subprocess hang 시 MCP server deadlock 가능성
• 일부 MCP spec conformance 문제
• Android Emulator에서 crash/recording device ID 불일치
• iOS Simulator stall
• Android IP 연결
• Flutter TextField 인식 문제 등이 올라와 있습니다. GitHub

따라서 일반적인 앱 테스트에는 충분히 쓸 만하지만, 대규모 production QA 전체를 즉시 이것 하나로 대체하는 수준은 아직 아닙니다.

---

15. 보안은 꼭 신경 써야 합니다

이 MCP는 일반 MCP보다 권한이 상당히 큽니다.

AI가 할 수 있는 것이:

앱 설치
앱 삭제
URL 열기
텍스트 입력
GPS 변경
클립보드 읽기
화면 내용 읽기
파일 생성

등이기 때문입니다.

프로젝트 자체도 별도 테스트용 디바이스 사용을 권장합니다. GitHub

그리고 과거에:

• Android Intent 실행 취약점
• screenshot/recording path traversal

두 건의 High 보안 Advisory도 있었습니다. 현재는 URL scheme 제한과 output path validation이 코드에 추가돼 있습니다. GitHub

그래서 HTTP 모드로 외부에 열 때는 반드시:

MOBILEMCP_AUTH=강력한토큰

을 설정하고, 가능하면 VPN/Tailscale 또는 TLS 뒤에 두는 구성이 좋습니다.

---

제가 이 프로젝트에서 가장 높게 보는 부분

이건 “모바일 테스트 MCP” 하나만 보고 보기에는 조금 아깝습니다.

결국 다음 구조를 가능하게 하기 때문입니다.

        AI Coding Agent
              │
   ┌──────────┼──────────┐
   ▼          ▼          ▼
 source     build      mobile
 code       system      MCP
   │          │          │
   │          │          ▼
   │          │       실제 App
   │          │          │
   │          │      UI / Logs
   │          │          │
   └──────────┴──────────┘
              │
              ▼
        Autonomous Loop

즉 Codex가 코드를 작성만 하는 게 아니라 자기 앱을 실제 휴대폰에서 사용해 보는 것이 가능해집니다.

그래서 모바일 개발용 하네스를 만든다면 저는 이런 구조가 상당히 적합하다고 봅니다.

AGENTS.md
   │
   ├─ Build Skill
   ├─ Android Skill
   ├─ iOS Skill
   └─ QA Skill
          │
          ▼
      Mobile MCP
          │
     ┌────┴────┐
     ▼         ▼
 Android     iPhone
 Emulator    Simulator
     │         │
     └────┬────┘
          ▼
      Test Result
          │
     ┌────┴─────┐
     ▼          ▼
   Logs      Screenshots
     │          │
     └────┬─────┘
          ▼
        Codex
          │
          ▼
      코드 수정
          │
          └────→ 재테스트

특히 AI Project Harness + Mobile MCP를 묶으면, 웹에서 Playwright를 붙이는 것과 비슷하게 모바일에서도 코드 작성 → Build → 설치 → 실제 UI 조작 → 로그 분석 → 자동 수정 루프를 만들 수 있다는 점이 가장 흥미로운 부분입니다.