개요
이 MCP 서버는 AI 에이전트가 iOS 및 Android 앱을 구조적으로 제어할 수 있게 해주며, 에뮬레이터, 시뮬레이터 및 실제 기기를 지원합니다. 네이티브 접근성 트리를 통해 앱을 우선적으로 구동하고, 필요한 경우 스크린샷과 좌표 클릭으로 폴백합니다. 또한 앱 관리, 제스처, 입력, 화면 녹화, 로그 및 크래시 리포트 등의 도구를 제공합니다.
README 미리보기
# Mobile Next - MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices\n\n**English** | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)\n\nThis is an MCP Server that enables scalable mobile automation, development through a platform-agnostic interface, eliminating the need for distinct iOS or Android knowledge. You can run it on emulators, simulators, and real devices (iOS and Android).\n\nThis server allows Agents and LLMs to interact with native iOS/Android applications and devices through structured accessibility snapshots or coordinate-based taps based on screenshots.\n\n**Works with Claude Code, Codex, Gemini, GitHub Copilot, Antigravity** — or any MCP-compatible client.\n\nRun it against devices on your own machine, or against real iOS and Android devices in the cloud with **[Mobile Next Cloud](https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=intro)** — same tools, no local setup.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n\nhttps://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde\n\n\n\n \n \n \n\n\n### Main use cases\n\nHow we help to scale mobile automation:\n\n- 📲 Native app automation (iOS and Android) for testing or data-entry scenarios.\n- 📝 Scripted flows and form interactions without manually controlling simulators/emulators or real devices (iPhone, Samsung, Google Pixel etc)\n- 🧭 Automating multi-step user journeys driven by an LLM\n- 👆 General-purpose mobile application interaction for agent-based frameworks\n- 🤖 Enables agent-to-agent communication for mobile automation usecases, data extraction\n\n## Main Features\n\n- 🚀 **Accessibility-first — fast and cheap**: drives apps from the native accessibility tree (no vision model, no image tokens), falling back to screenshots + coordinates only when needed.\n- 📱 **One API, every target**: the same tools work across
FAQ (2)
문제 해결도구 호출이 실패할 때 @mobilenext/mobile-mcp가 isError: true 대신 성공적인 MCP 결과를 반환하는 이유는 무엇인가요?
이것은 @mobilenext/mobile-mcp 1.0.8 및 1.0.9에서 알려진 버그입니다: 공유 도구 핸들러가 ActionableError를 catch한 후 isError: true 없이 텍스트 결과를 반환하므로, MCP 클라이언트가 실패한 작업(예: 존재하지 않는 디바이스로 mobile_get_screen_size를 호출하는 경우)을 성공으로 처리합니다. 수정 방법: createMcpServer()의 핸들러가 새로 export된 헬퍼 actionableErrorToolResult()를 통해 isError: true를 반환하는 PR #492가 포함된 릴리스로 업그레이드하세요. 1.0.9에 대한 우회 방법: 게시된 lib/server.js(또는 소스에서 빌드하는 경우 src/server.ts)를 패치하여 ActionableError 반환 객체에 isError: true를 추가해 다음과 같이 만드세요: return { content: [{ type: "text", text: ${error.message}. Please fix the issue and try again. }], isError: true };. 한 줄짜리 수정이 npm ci 후에도 유지되도록 버전 가드가 있는 postinstall 스크립트 또는 patch-package를 사용하세요.
문제 해결Amazon Q CLI를 mobile-mcp와 함께 사용할 때 mobile_take_screenshot으로 저장한 스크린샷이 열리지 않는 이유는 무엇인가요?
mobile_take_screenshot 도구는 이미지를 바이너리 PNG가 아닌 base64로 인코딩된 데이터로 반환합니다. 에이전트가 해당 base64 텍스트를 .png 파일에 그대로 쓰면 파일이 손상되어 OS에서 파일을 열 수 없다고 보고합니다. 해결 방법: 저장하기 전에 base64 페이로드를 디코딩하세요.
옵션 1 – 에이전트에게 명시적으로 프롬프트하기: "mobile_take_screenshot을 사용한 다음 base64 결과를 디코딩하고 바이너리 데이터를 /path/to/screenshot.png에 쓰세요."
옵션 2 – 터미널에서 수동으로 디코딩:
- Linux/macOS: base64 -d screenshot.txt > screenshot.png
- Python: python3 -c "import base64; open('screenshot.png','wb').write(base64.b64decode(open('screenshot.txt').read()))"
저장된 내용이 data:image/png;base64,로 시작하는 경우 디코딩하기 전에 해당 접두사를 제거하세요. 디코딩 후에는 PNG가 모든 이미지 뷰어에서 정상적으로 열립니다.