Claude Mobile

모바일 및 데스크톱 자동화를 위한 MCP 서버 — Android(ADB 경유), iOS 시뮬레이터(simctl 경유), 데스크톱(Compose Multiplatform) 및 Aurora OS(audb 경유). Claude in Chrome과 유사하지만 모바일 기기 및 데스크톱 앱을 위한 도구입니다.

Claude를 통해 자연어로 Android 폰, 에뮬레이터, iOS 시뮬레이터, 데스크톱 애플리케이션 또는 Aurora OS 기기를 제어하세요.

주요 기능

통합 API — Android, iOS, 데스크톱, Aurora OS에서 동일한 명령 사용 가능
스마트 스크린샷 — 최적의 LLM 처리를 위해 자동 압축 (더 이상 거대한 이미지는 없습니다!)
주석이 달린 스크린샷 — 시각적 UI 이해를 돕기 위해 색상이 지정된 경계 상자와 번호가 매겨진 요소 레이블이 포함된 스크린샷
권한 관리 — 앱 권한을 프로그래밍 방식으로 부여, 취소 및 재설정 (Android 런타임 권한, iOS 개인정보 보호 서비스)
기기 로그 — 디버깅을 위한 필터가 포함된 logcat/시스템 로그 읽기
UI 상호작용 — 좌표 또는 요소 텍스트를 통한 탭, 길게 누르기, 스와이프
텍스트 입력 — 포커스된 필드에 입력
앱 제어 — 앱 실행, 중지 및 설치
플랫폼 선택 — Android, iOS, 데스크톱 또는 Aurora OS를 명시적으로 타겟팅
데스크톱 지원 — 창 관리, 클립보드 및 성능 지표를 사용하여 Compose Multiplatform 데스크톱 앱 테스트

설치

Homebrew를 통한 네이티브 CLI (macOS)

brew tap AlexGladkov/claude-in-mobile https://github.com/AlexGladkov/claude-in-mobile
brew install claude-in-mobile

이 CLI는 모든 기기 자동화 도구와 스토어 관리(Google Play, Huawei AppGallery, RuStore)를 포함합니다:

claude-in-mobile screenshot android
claude-in-mobile tap android 540 960 --from-size 540x960
claude-in-mobile store upload --package com.example.app --file app.aab
claude-in-mobile huawei upload --package com.example.app --file app.aab
claude-in-mobile rustore upload --package com.example.app --file app.apk

한 줄 설치 (모든 클라이언트)

add-mcp 사용 — 설치된 클라이언트를 자동 감지합니다:

npx add-mcp claude-in-mobile -y

또는 특정 클라이언트를 타겟팅하세요:

npx add-mcp claude-in-mobile -a claude-code -y
npx add-mcp claude-in-mobile -a opencode -y
npx add-mcp claude-in-mobile -a cursor -y

Claude Code CLI

claude mcp add --transport stdio mobile -- npx claude-in-mobile@latest

전역으로 추가하려면 (모든 프로젝트에서 사용 가능):

claude mcp add --scope user --transport stdio mobile -- npx claude-in-mobile@latest

OpenCode

대화형 설정을 사용하세요:

opencode mcp add

또는 opencode.json(프로젝트 루트 또는 ~/.config/opencode/opencode.json)에 수동으로 추가하세요:

{
  "mcp": {
    "mobile": {
      "type": "local",
      "command": ["npx", "-y", "claude-in-mobile"],
      "enabled": true
    }
  }
}

Cursor

.cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "mobile": {
      "command": "npx",
      "args": ["-y", "claude-in-mobile"]
    }
  }
}

모든 MCP 클라이언트

클라이언트를 위한 설정 스니펫을 출력하세요:

npx claude-in-mobile --init <client-name>
# Supported: opencode, cursor, claude-code

npm에서 설치

npx claude-in-mobile

소스에서 설치

git clone https://github.com/AlexGladkov/claude-in-mobile.git
cd claude-in-mobile
npm install
npm run build:all  # Builds TypeScript + Desktop companion

참고: 데스크톱 지원을 위해서는 데스크톱 컴패니언 앱을 컴파일하기 위해 npm run build:desktop(또는 build:all)을 실행해야 합니다.

MCP 클라이언트와 함께 로컬 빌드 사용하기

소스에서 빌드한 후, npx를 사용하는 대신 MCP 클라이언트가 로컬 dist/index.js를 가리키도록 설정하세요:

{
  "mcpServers": {
    "mobile": {
      "command": "node",
      "args": ["/path/to/claude-in-mobile/dist/index.js"]
    }
  }
}

OpenCode(opencode.json)의 경우:

{
  "mcp": {
    "mobile": {
      "type": "local",
      "command": ["node", "/path/to/claude-in-mobile/dist/index.js"],
      "enabled": true
    }
  }
}

수동 설정

Claude Code 설정(~/.claude.json 또는 프로젝트 설정)에 추가하세요:

{
  "mcpServers": {
    "mobile": {
      "command": "npx",
      "args": ["-y", "claude-in-mobile"]
    }
  }
}

Windows

claude mcp add --transport stdio mobile -- cmd /c npx claude-in-mobile@latest

요구 사항

Android

ADB가 설치되어 있고 PATH에 포함되어 있어야 함
연결된 Android 기기(USB 디버깅 활성화됨) 또는 에뮬레이터

iOS

Xcode가 설치된 macOS
iOS 시뮬레이터(물리적 기기 지원은 아직 없음)
전체 UI 검사 및 요소 기반 상호작용을 위한 WebDriverAgent:
```
npm install -g appium
appium driver install xcuitest
```
또는 WDA_PATH 환경 변수를 사용자 지정 WebDriverAgent 위치로 설정하세요.

데스크톱

macOS (Windows/Linux 지원 예정)
데스크톱 컴패니언 빌드를 위한 JDK 17+
테스트할 Compose Multiplatform 데스크톱 애플리케이션

Aurora OS

audb CLI가 설치되어 있고 PATH에 포함되어 있어야 함 (cargo install audb-client)
SSH가 활성화된 연결된 Aurora OS 기기
탭/스와이프를 위해 기기에 Python 필요: devel-su pkcon install python

사용 가능한 도구

핵심 도구 (모든 플랫폼)

도구	Android	iOS	데스크톱	Aurora	설명
`list_devices`	✅	✅	✅	✅	연결된 모든 기기 나열
`set_device`	✅	✅	✅	✅	활성 기기 선택
`screenshot`	✅	✅	✅	✅	스크린샷 촬영
`tap`	✅	✅	✅	⚠️	좌표 또는 텍스트/레이블로 탭 (iOS: 요소 탭을 위해 WDA 필요)
`long_press`	✅	✅	✅	✅	길게 누르기 제스처
`swipe`	✅	✅	✅	⚠️	방향 또는 좌표로 스와이프 (Aurora에서는 Python 필요)
`input_text`	✅	✅	✅	❌	텍스트 입력
`press_key`	✅	✅	✅	✅	하드웨어 버튼 누르기
`launch_app`	✅	✅	❌	✅	앱 실행
`stop_app`	✅	✅	❌	✅	앱 중지
`install_app`	✅	✅	❌	✅	APK/.app/.rpm 설치
`list_apps`	❌	❌	❌	✅	설치된 앱 나열 (Aurora 전용)
`get_ui`	✅	✅	✅	❌	UI 계층 구조 가져오기 (iOS: WebDriverAgent 필요)
`find_element`	✅	✅	✅	❌	텍스트/ID/레이블로 요소 찾기 (iOS: WebDriverAgent 필요)
`annotate_screenshot`	✅	✅	❌	❌	색상이 지정된 경계 상자와 번호가 매겨진 요소 레이블이 포함된 스크린샷
`grant_permission`	✅	✅	❌	❌	앱 권한 부여 (Android: 런타임, iOS: 개인정보 보호 서비스)
`revoke_permission`	✅	✅	❌	❌	앱 권한 취소
`reset_permissions`	✅	✅	❌	❌	앱의 모든 권한 재설정
`get_current_activity`	✅	❌	❌	❌	포그라운드 활동 가져오기
`open_url`	✅	✅	❌	❌	브라우저에서 URL 열기 (Aurora에서는 아직 구현되지 않음)
`shell`	✅	✅	❌	✅	셸 명령 실행
`wait`	✅	✅	✅	✅	지정된 시간 동안 대기
`get_logs`	✅	✅	❌	✅	기기 로그 가져오기 (logcat/시스템 로그)
`clear_logs`	✅	⚠️	❌	✅	로그 버퍼 지우기
`get_system_info`	✅	❌	❌	✅	배터리, 메모리 정보
`wait_for_element`	✅	✅	❌	❌	요소가 나타날 때까지 대기 (폴링 + 타임아웃)
`assert_visible`	✅	✅	❌	❌	요소가 보이는지 확인 (성공/실패)
`assert_not_exists`	✅	✅	❌	❌	요소가 존재하지 않는지 확인 (성공/실패)
`batch_commands`	✅	✅	✅	✅	단일 왕복으로 여러 명령 실행
`get_webview`	✅	❌	❌	❌	Chrome DevTools Protocol을 통해 WebView 검사
`push_file`	❌	❌	❌	✅	파일 업로드 (Aurora 전용)
`pull_file`	❌	❌	❌	✅	파일 다운로드 (Aurora 전용)

데스크톱 전용 도구

도구	설명
`set_target`	타겟 플랫폼 설정 (android/ios/desktop)
`get_target`	현재 타겟 플랫폼 가져오기
`launch_desktop_app`	Compose 데스크톱 애플리케이션 실행
`stop_desktop_app`	실행 중인 데스크톱 애플리케이션 중지
`get_window_info`	데스크톱 창 위치 및 크기 가져오기
`focus_window`	데스크톱 창을 맨 앞으로 가져오기
`resize_window`	데스크톱 창 크기 조정
`get_clipboard`	시스템 클립보드 내용 가져오기
`set_clipboard`	시스템 클립보드 내용 설정
`get_performance_metrics`	데스크톱 앱의 CPU/메모리 사용량 가져오기

자세한 데스크톱 API 문서는 Desktop Specification을 참조하세요.

사용 예시

Claude와 자연스럽게 대화하세요:

"Show me all connected devices"
"Take a screenshot of the Android emulator"
"Take a screenshot on iOS"
"Tap on Settings"
"Swipe down to scroll"
"Type 'hello world' in the search field"
"Press the back button on Android"
"Open Safari on iOS"
"Switch to iOS simulator"
"Run the app on both platforms"

권한 관리

"Grant camera permission to com.example.app on Android"
"Revoke location access from com.example.app"
"Reset all permissions for com.apple.Maps on iOS"

주석이 달린 스크린샷

"Take an annotated screenshot"  → Screenshot with green (clickable) and red (non-clickable) bounding boxes + numbered element index

플랫폼 선택

플랫폼을 명시적으로 지정할 수 있습니다:

"Screenshot on android"     → Uses Android device
"Screenshot on ios"         → Uses iOS simulator
"Screenshot on desktop"     → Uses Desktop app
"Screenshot on aurora"      → Uses Aurora OS device
"Screenshot"                → Uses last active device

또는 활성 기기를 설정하세요:

"Use the iPhone 15 simulator"
"Switch to the Android emulator"
"Switch to desktop"
"Switch to Aurora device"

데스크톱 예시

"Launch my desktop app from /path/to/app"
"Take a screenshot of the desktop app"
"Get window info"
"Resize window to 1280x720"
"Tap at coordinates 100, 200"
"Get clipboard content"
"Set clipboard to 'test text'"
"Get performance metrics"
"Stop the desktop app"

Aurora 예시

"List all Aurora devices"
"Take a screenshot on Aurora"
"Tap at coordinates 100, 200 on Aurora"
"Launch ru.example.app on Aurora"
"List installed apps on Aurora device"
"Get logs from Aurora device"
"Push file.txt to /home/defaultuser/ on Aurora device"

네이티브 CLI

동일한 모든 명령을 포함하는 2MB 크기의 네이티브 Rust 바이너리입니다. Node.js나 종속성이 필요 없습니다.

CLI 설치

brew tap AlexGladkov/claude-in-mobile
brew install claude-in-mobile

또는 Releases에서 다운로드하세요.

MCP 대비 장점

쉬운 설치 — brew install 또는 2MB 바이너리 하나만 복사
종속성 없음 — Node.js, npm 등이 필요 없음
터미널에서 사용 — Claude Code나 MCP 클라이언트 없이 명령을 직접 실행
테스트 자동화 — 플랫폼 내부 구조를 배울 필요 없이 모든 플랫폼에 대해 범용 .sh 스크립트 작성
토큰 효율적 — 기술 문서는 사용될 때만 로드됨; MCP는 모든 도구 스키마를 모든 요청에 로드하므로 세션이 길어질수록 토큰 소모가 큼
빠름 — ~5ms 명령 시작(Rust) vs ~500ms(Node.js MCP)
CI/CD 준비 완료 — 종료 코드, stdout/stderr, 어디서나 실행 가능

테스트 스크립트 예시

#!/bin/bash
claude-in-mobile launch android com.example.app
claude-in-mobile wait 2000
claude-in-mobile tap android 0 0 --text "Login"
claude-in-mobile input android "test@example.com"
claude-in-mobile screenshot android -o result.png
claude-in-mobile ui-dump android | grep "Welcome" && echo "PASS" || echo "FAIL"

Claude Code 플러그인

claude plugin marketplace add AlexGladkov/claude-in-mobile
claude plugin install claude-in-mobile@claude-in-mobile

설치 후, Claude Code는 자연어로 기기를 제어합니다. 기술은 필요할 때만 컨텍스트로 로드되므로 사용하지 않을 때는 토큰 오버헤드가 없습니다.

전체 CLI 문서는 cli/README.md를 참조하세요.

iOS WebDriverAgent 설정

전체 iOS UI 검사 및 요소 기반 상호작용을 위해서는 WebDriverAgent가 필요합니다. 다음 기능을 활성화합니다:

get_ui - JSON 접근성 트리 검사
label 또는 text 매개변수를 사용한 tap - 요소 기반 탭
find_element - 요소 발견 및 쿼리
swipe - 향상된 제스처 시뮬레이션

설치

자동 (Appium 경유):

npm install -g appium
appium driver install xcuitest

수동: WDA_PATH 환경 변수를 WebDriverAgent 위치로 설정하세요:

export WDA_PATH=/path/to/WebDriverAgent

첫 사용

처음 사용할 때 WebDriverAgent는 자동으로 다음 과정을 거칩니다:

Appium 설치 또는 WDA_PATH에서 발견
xcodebuild로 빌드 (1회성, 약 2분)
iOS 시뮬레이터에서 실행
8100+ 포트에서 HTTP를 통해 연결

문제 해결

빌드 실패:

# Install Xcode command line tools
xcode-select --install

# Accept license
sudo xcodebuild -license accept

# Set Xcode path
sudo xcode-select -s /Applications/Xcode.app

세션 실패:

시뮬레이터가 부팅되었는지 확인: xcrun simctl list | grep Booted
포트 가용성 확인: lsof -i :8100
시뮬레이터 재시작 시도

수동 테스트:

cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
xcodebuild test -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'platform=iOS Simulator,id=<DEVICE_UDID>'

작동 원리

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ Claude Code │────▶│                  │────▶│  Android (ADB)  │
├─────────────┤     │  Claude Mobile   │     └─────────────────┘
│  OpenCode   │────▶│   MCP Server     │     ┌─────────────────┐
├─────────────┤     │                  │────▶│ iOS (simctl+WDA)│
│   Cursor    │────▶│  (auto-detects   │     └─────────────────┘
├─────────────┤     │   client via     │     ┌─────────────────┐
│  Any MCP    │────▶│   MCP protocol)  │────▶│ Desktop (Compose)│
│   Client    │     │                  │     └─────────────────┘
└─────────────┘     │                  │     ┌─────────────────┐
                    │                  │────▶│ Aurora (audb)   │
                    └──────────────────┘     └─────────────────┘

Claude가 MCP 프로토콜을 통해 명령을 보냄
서버가 적절한 플랫폼(ADB, simctl+WDA, 데스크톱 컴패니언 또는 audb)으로 라우팅
기기 또는 데스크톱 앱에서 명령 실행
결과(스크린샷, UI 데이터, 지표)가 Claude로 반환

라이선스

MIT