Mobile MCP
- 추천0
- GitHub 별11K
- 개발라이선스Apache-2.0
AI 에이전트가 iOS · Android 시뮬레이터 · 에뮬레이터 · 실기기 앱을 조작하게 해 주는 MCP 서버. Apache-2.0
설치 방법은 설치 탭에 정리했어요.
설명
Mobile Next - 모바일 개발 · 자동화용 MCP 서버 | iOS, Android, 시뮬레이터, 에뮬레이터, 실기기
이것은 iOS나 Android의 별도 지식 없이도, 플랫폼에 구애받지 않는 인터페이스로 확장 가능한 모바일 자동화와 개발을 가능하게 하는 MCP 서버입니다. 에뮬레이터, 시뮬레이터, 실기기(iOS와 Android)에서 돌릴 수 있습니다.
이 서버는 에이전트와 LLM이 구조화된 접근성 스냅샷, 또는 스크린샷에 기반한 좌표 탭으로 네이티브 iOS/Android 앱과 기기를 다루게 해 줍니다.
Claude Code, Codex, Gemini, GitHub Copilot, Antigravity와 함께 동작합니다 — 또는 MCP를 지원하는 모든 클라이언트와도 됩니다.
내 컴퓨터에 있는 기기를 대상으로 돌리거나, **Mobile Next Cloud**로 클라우드의 실제 iOS · Android 기기를 대상으로 돌릴 수 있습니다 — 같은 도구, 로컬 설정은 필요 없습니다.
https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
🚀 빠른 시작
빠른 설치는 이 컴퓨터에 있는 MCP 클라이언트(Claude Code, Codex, Cursor, VS Code, Gemini CLI 등)를 찾아서, 어느 것을 설정할지 고르게 해 줍니다.
npx @mobilenext/mobile-mcp@latest install
묻지 않고 찾은 클라이언트를 모두 설정하려면 --yes를 붙이세요.
클라이언트별 수동 설정은 아래 「설치와 설정」을 보세요.
주요 사용 사례
모바일 자동화를 확장하는 데 도움이 되는 방식입니다.
- 📲 테스트나 데이터 입력 시나리오를 위한 네이티브 앱 자동화(iOS와 Android).
- 📝 시뮬레이터/에뮬레이터나 실기기(iPhone, Samsung, Google Pixel 등)를 직접 조작하지 않고 스크립트로 만든 흐름과 폼 상호작용
- 🧭 LLM이 이끄는 여러 단계의 사용자 여정 자동화
- 👆 에이전트 기반 프레임워크를 위한 범용 모바일 애플리케이션 상호작용
- 🤖 모바일 자동화 사용 사례와 데이터 추출을 위한 에이전트 간 통신 지원
주요 기능
- 🚀 접근성 우선 — 빠르고 저렴: 비전 모델이나 이미지 토큰 없이 네이티브 접근성 트리로 앱을 구동하고, 필요할 때만 스크린샷 + 좌표로 대체합니다.
- 📱 하나의 API, 모든 대상: 같은 도구가 iOS와 Android의 시뮬레이터, 에뮬레이터, 실기기 모두에서 동작합니다.
- 🧠 플랫폼 전문 지식이 필요 없음: XCUITest도, Espresso도, 플랫폼별 연결 코드도 필요 없습니다 — 목표를 설명하면 에이전트가 해냅니다.
- 🧰 기기 전체 제어: 탭, 스와이프, 제스처. 앱 설치 · 실행 · 종료. 화면 녹화. 하드웨어 버튼. 딥링크. 화면 방향.
- 📊 구조화되고 결정적인 출력: 실제 UI 요소를 읽고 구조화된 데이터를 뽑아, 스크린샷만 쓰는 방식의 모호함을 줄입니다.
- 🪞 Claude Code의 기기 미러링: Ghostty나 kitty에서 돌리는 Claude Code용입니다. 플러그인을 설치하고
/mobile-mirror를 실행하면 옆 창에 기기의 실시간 화면이 보이고, 터미널을 떠나지 않고 탭하고, 입력하고, Home/Back을 누를 수 있습니다.

🎯 플랫폼 지원
| 대상 | 지원 | 설정 |
|---|---|---|
| iOS 시뮬레이터 | ✅ | Xcode + 부팅한 시뮬레이터(xcrun simctl) |
| iOS 실기기 | ✅ | USB로 연결하고 신뢰한 기기 |
| Android 에뮬레이터 | ✅ | Android SDK + 실행 중인 에뮬레이터(adb) |
| Android 실기기 | ✅ | adb + USB 디버깅 켜고 허용 |
🔧 사용할 수 있는 MCP 도구
기기 관리
mobile_list_available_devices- 사용할 수 있는 모든 기기(시뮬레이터, 에뮬레이터, 실기기)를 나열합니다mobile_get_screen_size- 모바일 기기의 화면 크기를 픽셀로 가져옵니다mobile_get_orientation- 기기의 현재 화면 방향을 가져옵니다mobile_set_orientation- 화면 방향을 바꿉니다(세로/가로)mobile_fold_device- 폴더블 기기를 접거나 펼칩니다(iPhone Duo 시뮬레이터, 폴더블 Android 에뮬레이터)mobile_set_location- 기기가 알리는 GPS 위치를 덮어쓰거나 덮어쓴 값을 지웁니다mobile_clipboard- 기기 클립보드를 읽거나 바꿉니다
원격 기기(Mobile Next Cloud)
mobile_login_to_cloud_provider- 이 컴퓨터를 클라우드 기기 제공자에 인증합니다(브라우저 기반 기기 코드 로그인)mobile_list_remote_devices- 클라우드 기기 모음에서 예약할 수 있는 기기 모델을 나열합니다mobile_allocate_remote_device- 클라우드의 실제 기기를 독점으로 쓰도록 예약합니다mobile_release_remote_device- 예약한 클라우드 기기를 모음에 돌려줍니다
앱 관리
mobile_list_apps- 기기에 설치된 모든 앱을 나열합니다mobile_get_foreground_app- 지금 포그라운드에 있는 앱을 가져옵니다mobile_launch_app- 패키지 이름으로 앱을 실행합니다mobile_terminate_app- 실행 중인 앱을 멈추고 종료합니다mobile_install_app- 파일(.apk, .ipa, .app, .zip)로 앱을 설치합니다mobile_uninstall_app- 패키지 이름이나 번들 ID로 앱을 삭제합니다mobile_clear_app_data- 앱이 새로 시작하도록 앱 데이터를 지웁니다(Android와 iOS 시뮬레이터)
화면 상호작용
mobile_take_screenshot- 화면에 무엇이 있는지 알려고 스크린샷을 찍습니다mobile_save_screenshot- 스크린샷을 파일로 저장합니다mobile_list_elements_on_screen- UI 요소를 좌표와 속성과 함께 나열합니다mobile_click_on_screen_at_coordinates- 특정 x,y 좌표나 ref로 지정한 요소를 클릭합니다mobile_double_tap_on_screen- 특정 좌표나 ref로 지정한 요소를 두 번 탭합니다mobile_long_press_on_screen_at_coordinates- 특정 좌표나 ref로 지정한 요소를 길게 누릅니다mobile_swipe_on_screen- 어느 방향으로든 스와이프합니다(위, 아래, 왼쪽, 오른쪽)mobile_start_screen_recording- 기기 화면을 동영상 파일로 녹화하기 시작합니다mobile_stop_screen_recording- 진행 중인 화면 녹화를 멈추고 영상을 저장합니다
입력과 탐색
mobile_type_keys- 포커스된 요소에 글자를 입력합니다(선택으로 제출까지)mobile_press_button- 기기 단추(HOME, BACK, VOLUME_UP/DOWN, ENTER 등)를 누릅니다mobile_open_url- 기기 브라우저에서 http/https 주소를 엽니다
로그와 크래시 보고서
mobile_get_device_logs- 기기의 실시간 로그(Android는 logcat, iOS는 통합 로그)를 모으며, 선택으로 파일에 저장합니다mobile_list_crashes- 기기에 있는 크래시 보고서를 나열합니다mobile_get_crash- ID로 크래시 보고서의 전체 내용을 가져옵니다mobile_batch_commands- 여러 도구를 한 번의 호출로 차례로 실행합니다(예: 클릭, 입력, 클릭). 선택으로 끝에 화면 요소를 나열합니다
🏗️ Mobile MCP 구조
📚 위키 페이지
설정, 구성, 디버깅 관련 질문은 위키 페이지에 더 자세히 있습니다.
준비물
MCP를 내 에이전트와 모바일 기기에 연결하려면 다음이 필요합니다.
- Xcode 명령줄 도구
- Android Platform Tools
- node.js v20 이상
- Claude MCP, OpenAI Agent SDK, Copilot Studio 같은 MCP를 지원하는 기반 모델이나 에이전트
설치와 설정
직접 설정하려면 대부분의 도구에서 통하는 이 표준 설정을 쓰세요.
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
Amp
Amp VS Code 확장의 설정 화면에서 추가하거나 settings.json 파일을 고쳐서 추가하세요.
"amp.mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
Amp CLI:
터미널에서 다음 명령을 실행하세요.
amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
Antigravity 2
Antigravity에는 MCP 서버를 추가하는 CLI 명령이 없으므로 직접 추가하세요. ~/.gemini/config/mcp_config.json을 열어 다음을 넣습니다.
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
Cline
Cline을 설정하려면 위의 json을 MCP 설정 파일에 추가하면 됩니다.
Claude Code
Claude Code 안에서 플러그인을 설치하세요. Mobile MCP 서버와 /mobile-mirror가 함께 들어옵니다.
/plugin marketplace add mobile-next/mobile-mcp
/plugin install mobile-mcp@mobile-mcp
/mobile-mirror [device-id]는 기기의 실시간 화면이 보이는 창을 엽니다. 그림을 클릭하면 탭하고, 입력하면 키를 보내고, 위쪽의 Home, Back, 앱 전환, URL 단추를 쓸 수 있습니다. 그림을 보려면 kitty나 Ghostty처럼 kitty 그래픽 프로토콜을 지원하는 터미널이 필요합니다.
플러그인을 쓸 수 없다면 Claude Code CLI로 MCP 서버만 추가하세요.
claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
Claude Desktop
MCP 설치 안내를 따르고, 위의 json 설정을 쓰세요.
Codex
Codex CLI로 Mobile MCP 서버를 추가하세요.
codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
또는 설정 파일 ~/.codex/config.toml을 만들거나 고쳐서 다음을 추가하세요.
[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]
자세한 내용은 Codex MCP 문서를 보세요.
Copilot
Copilot CLI로 Mobile MCP 서버를 대화형으로 추가하세요.
/mcp add
설정 파일 ~/.copilot/mcp-config.json을 고쳐서 다음을 추가할 수도 있습니다.
{
"mcpServers": {
"mobile-mcp": {
"type": "local",
"command": "npx",
"tools": [
"*"
],
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
자세한 내용은 Copilot CLI 문서를 보세요.
Cursor
단추를 눌러 설치하기
또는 직접 설치하기
Cursor Settings -> MCP -> Add new MCP Server로 가세요. 이름은 원하는 대로 정하고, command 종류에 npx -y @mobilenext/mobile-mcp@latest 명령을 쓰세요. Edit를 눌러 설정을 확인하거나 명령에 인자를 더할 수도 있습니다.
Gemini CLI
Gemini CLI로 Mobile MCP 서버를 추가하세요.
gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
Goose
단추를 눌러 설치하기
또는 직접 설치하기
Advanced settings -> Extensions -> Add custom extension으로 가세요. 이름은 원하는 대로 정하고, 종류는 STDIO, command는 npx -y @mobilenext/mobile-mcp@latest로 두세요. "Add Extension"을 누르세요.
Kiro
MCP 서버 문서를 따르세요. 예를 들어 .kiro/settings/mcp.json에 다음과 같이 넣습니다.
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
opencode
MCP 서버 문서를 따르세요. 예를 들어 ~/.config/opencode/opencode.json에 다음과 같이 넣습니다.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mobile-mcp": {
"type": "local",
"command": [
"npx",
"@mobilenext/mobile-mcp@latest"
],
"enabled": true
}
}
}
Windsurf
Windsurf 설정을 열고 MCP 서버로 이동해, command 종류로 다음을 넣어 새 서버를 추가하세요.
npx @mobilenext/mobile-mcp@latest
또는 위에 보인 표준 설정을 설정의 mcpServers 아래에 추가하세요.
✅ 동작 확인
서버 설정이 끝나면 에이전트에게 기기 목록을 보여 달라고 하세요.
list available devices
실행 중인 시뮬레이터, 에뮬레이터, 연결된 기기가 돌아와야 합니다. 그렇다면 Mobile MCP가 제대로 연결된 것입니다. 목록이 비어 있다면 시뮬레이터나 에뮬레이터가 실행 중인지 확인하세요(위의 「준비물」). 더 도움이 필요하면 위키를 확인하세요.
🧪 에이전트 세션에서 CI 테스트로
모바일 앱을 자동화하거나 테스트하려고 Mobile MCP를 쓰고 있나요? 에이전트에게 그 흐름을 Mobilewright 테스트로 쓰라고 하세요. 결정적인 테스트가 되어 CI/CD 흐름의 일부가 됩니다.
import { test, expect } from '@mobilewright/test';
test('sign in', async ({ screen }) => {
await screen.getByLabel('Email').fill('user@example.com');
await screen.getByRole('button', { name: 'Sign In' }).tap();
await expect(screen.getByText('Welcome back')).toBeVisible();
});
npm init mobilewright@latest로 시작하세요. 단계별 안내는 에이전트 세션에서 GitHub Actions에서 도는 테스트까지 이어 줍니다.
☁️ 규모 키우기, 클라우드 기기 쓰기
수백 대의 기기로 규모를 키우고 싶나요? CI/CD 파이프라인에서 Mobile MCP를 쓰고 싶나요?
에이전트에게 이렇게 프롬프트를 주세요.
log in to mobile next cloud and then show me which remote devices are available to me
Streamable HTTP 서버 모드
기본적으로 Mobile MCP는 stdio로 돕니다. 대신 Streamable HTTP 서버를 시작하려면 --listen 플래그를 쓰세요.
npx @mobilenext/mobile-mcp@latest --listen 3000
이 명령은 localhost:3000에 바인딩합니다. 특정 인터페이스에 바인딩하려면 이렇게 하세요.
npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000
그런 다음 MCP 클라이언트가 http://<host>:3000/mcp(TLS 뒤에서는 https://…/mcp)에 연결하도록 설정하세요. 엔드포인트는 Streamable HTTP(/mcp에 POST)를 받으며, 원격 모드는 상태를 따로 유지하지 않아서(세션 고정이 필요 없음) Smithery 같은 수평 확장 호스트와 잘 맞습니다.
💡 이전 안내
--listen은 예전에/mcp에서 더는 권장하지 않는 HTTP+SSE 전송을 제공했습니다. 이제 클라이언트는http(s)://host:port/mcp에서 Streamable HTTP를 써야 합니다./mcp의 옛 순수 SSE 방식은 더는 쓸 수 없습니다.
localhost에 바인딩하면 Host 헤더 DNS 리바인딩 보호가 자동으로 켜집니다.
인증
HTTP 서버에 Bearer 토큰 인증을 요구하려면 MOBILEMCP_AUTH 환경 변수를 정하세요.
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
정하면 모든 요청에 Authorization: Bearer my-secret-token 헤더가 있어야 합니다. 정하지 않으면 서버는 인증 없는 연결을 받고 경고를 남깁니다.
🛠️ 사용 방법
내 IDE/클라이언트에 MCP 서버를 추가한 뒤에는 AI 어시스턴트에게 사용할 수 있는 도구를 쓰라고 지시하면 됩니다. 예를 들어 Cursor의 에이전트 모드에서 아래 프롬프트로 UI 상호작용을 빠르게 검증 · 테스트 · 반복하고, 화면에서 정보를 읽고, 복잡한 작업 흐름을 따라갈 수 있습니다. 구체적으로, 요점만 곧바로 말하세요.
✨ 예시 프롬프트
작업 흐름
하나의 프롬프트에 자세한 작업 흐름을 정해, 비즈니스 로직을 검증하고, 자동화를 구성할 수 있습니다. 마음껏 해 보세요.
동영상을 검색하고, 댓글을 달고, 좋아요를 누르고, 공유하기
Find the video called " Beginner Recipe for Tonkotsu Ramen" by Way of
Ramen, click on like video, after liking write a comment " this was
delicious, will make it next Friday", share the video with the first
contact in your whatsapp list.
잘 나가는 만보기 앱을 내려받고, 가입하고, 운동을 설정하고, 앱에 별 5개 주기
Find and Download a free "Pomodoro" app that has more than 1k stars.
Launch the app, register with my email, after registration find how to
start a pomodoro timer. When the pomodoro timer started, go back to the
app store and rate the app 5 stars, and leave a comment how useful the
app is.
Substack에서 검색하고, 읽고, 강조하고, 댓글을 달고, 글을 저장하기
Open Substack website, search for "Latest trends in AI automation 2025",
open the first article, highlight the section titled "Emerging AI trends",
and save article to reading list for later review, comment a random
paragraph summary.
운동 수업을 예약하고 타이머 설정하기
Open ClassPass, search for yoga classes tomorrow morning within 2 miles,
book the highest-rated class at 7 AM, confirm reservation,
setup a timer for the booked slot in the phone
지역 행사를 찾고 캘린더 일정 설정하기
Open Eventbrite, search for AI startup meetup events happening this
weekend in "Austin, TX", select the most popular one, register and RSVP
yes to the event, setup a calendar event as a reminder.
날씨 예보를 확인하고 Whatsapp/Telegram/Slack 메시지 보내기
Open Weather app, check tomorrow's weather forecast for "Berlin", and
send the summary via Whatsapp/Telegram/Slack to contact "Lauren Trown",
thumbs up their response.
- Zoom에서 회의를 잡고 이메일로 초대장 공유하기
Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
10AM with a duration of 1 hour, copy the invitation link, and send it via
Gmail to contacts "team@example.com".
실행과 설정
환경 변수
| 변수 | 설명 | 예시 |
|---|---|---|
MOBILEMCP_AUTH | Streamable HTTP 서버(--listen)에 Bearer 토큰을 요구합니다 — 그러면 모든 요청이 Authorization: Bearer <token>을 보내야 합니다. | MOBILEMCP_AUTH=my-secret-token |
MOBILEMCP_DISABLE_TELEMETRY | 익명 사용 통계를 끕니다. | MOBILEMCP_DISABLE_TELEMETRY=1 |
MOBILEMCP_ALLOW_UNSAFE_URLS | mobile_open_url이 표준이 아닌 URL 스킴을 열 수 있게 합니다(기본은 막혀 있음). | MOBILEMCP_ALLOW_UNSAFE_URLS=1 |
MOBILEMCP_LEGACY_ROBOT | Android 기기와 실제 iOS 기기에 옛 플랫폼별 로봇을 씁니다. iOS 시뮬레이터는 계속 mobilecli를 씁니다. | MOBILEMCP_LEGACY_ROBOT=1 |
시뮬레이터, 에뮬레이터, 실기기
실행하면 Mobile MCP는 다음에 연결할 수 있습니다.
- macOS/Linux의 iOS 시뮬레이터
- Linux/Windows/macOS의 Android 에뮬레이터
- iOS나 Android 실기기(알맞은 플랫폼 도구와 드라이버가 필요)
Mobile Next Mobile MCP를 실행하기 전에 모바일 플랫폼 SDK(Xcode, Android SDK)가 설치되어 제대로 설정되어 있는지 확인하세요.
텔레메트리
Mobile MCP는 PostHog와 Scarf로 익명 사용 통계를 모읍니다. 끄려면 MOBILEMCP_DISABLE_TELEMETRY 환경 변수를 정하세요.
MOBILEMCP_DISABLE_TELEMETRY=1 npx @mobilenext/mobile-mcp@latest
json 설정에서는 이렇게 합니다.
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"],
"env": {
"MOBILEMCP_DISABLE_TELEMETRY": "1"
}
}
}
}
시뮬레이터/에뮬레이터에서 "헤드리스" 모드로 실행하기
내 컴퓨터에 연결한 실기기가 없을 때는 에뮬레이터나 시뮬레이터를 백그라운드에 두고 Mobile MCP를 실행할 수 있습니다.
예를 들어 Android에서는 이렇게 합니다.
- 에뮬레이터를 시작합니다(avdmanager / emulator 명령).
- 원하는 플래그로 Mobile MCP를 실행합니다.
iOS에서는 그 시뮬레이터 인스턴스로 Mobile MCP를 쓰기 전에 Xcode가 필요하고 시뮬레이터를 실행해야 합니다.
xcrun simctl listxcrun simctl boot "iPhone 16"
🧩 Mobile Next의 일부
Mobile MCP는 실제 모바일 기기를 구동하는 도구 모음의 한 조각입니다.
- mobilewright — "모바일용 Playwright". 에이전트가 이끈 탐색을 iOS와 Android의 반복 가능한 결정적 테스트로 바꿀 준비가 되면 mobilewright로 넘어가세요.
- mobilecli — Mobile MCP가 기반으로 삼는 범용 기기 CLI입니다. 명령줄이나 JSON-RPC API로 기기, 시뮬레이터, 에뮬레이터를 제어합니다.
- Mobile Next Cloud — 같은 스택을 빌려 쓰는 것: 필요할 때 실제 iOS · Android 기기를 씁니다. 에이전트에게
log in to mobile next cloud and then show me which remote devices are available to me라고 하면 시작됩니다.
🚀 로드맵
Mobile MCP를 계속 개선하고 있습니다. 다음에 무엇을 만드는지는 ROADMAP.md에서 보세요 — 우선순위는 커뮤니티 의견에 크게 좌우되므로 보고 싶은 것을 알려 주세요.
🤝 기여하기
기여를 환영합니다 — 코드, 문서, 버그 보고, 아이디어 모두요.
- ⭐ 저장소에 별 달기 — 다른 사람들이 Mobile MCP를 발견하도록 돕는 가장 쉬운 방법입니다.
- 빌드, 테스트, 풀 리퀘스트를 여는 방법은 CONTRIBUTING.md를 읽어 보세요.
- 열린 이슈를 살펴 작업할 것을 찾아보세요.
- 질문과 아이디어는 Slack 커뮤니티에서도 환영합니다.
행동 강령도 함께 읽어 주세요.
모든 기여자께 감사드립니다 ❤️
이 프로젝트를 개선하는 데 도움을 준 모든 분께 감사드립니다.
개인정보 처리방침
Mobile MCP는 로컬에서 실행되며 내가 연결한 기기하고만 통신합니다. 데이터 수집 · 사용 · 보관 · 연락처 정보는 Mobile Next 개인정보 처리방침(https://mobilenext.ai/privacy)을 보세요.

