mobile-mcp
Applicationmobile-next/mobile-mcp
MCP server that lets AI agents automate iOS and Android apps on any device.
Overview
An MCP server giving AI agents structured control over iOS and Android apps on simulators, emulators and real devices. It drives apps via the native accessibility tree, falling back to screenshots and coordinate taps when needed. Also covers app management, gestures, input, screen recording, logs and crash reports.
README Preview
# 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)
TroubleshootingWhy does @mobilenext/mobile-mcp return a successful MCP result instead of isError: true when a tool call fails?
This is a known bug in @mobilenext/mobile-mcp 1.0.8 and 1.0.9: the shared tool handler catches ActionableError and returns a text result without isError: true, so MCP clients treat failed operations (e.g., calling mobile_get_screen_size with a nonexistent device) as successful. Fix: upgrade to the release containing PR #492, where the handler in createMcpServer() returns isError: true via the new exported helper actionableErrorToolResult(). Workaround for 1.0.9: patch the published lib/server.js (or src/server.ts if building from source) by adding isError: true to the ActionableError return object, so it reads: return { content: [{ type: "text", text: ${error.message}. Please fix the issue and try again. }], isError: true };. Use a postinstall script or patch-package with a version guard so the one-line fix survives npm ci.
TroubleshootingWhy won't the screenshot saved from mobile_take_screenshot open when using Amazon Q CLI with mobile-mcp?
The mobile_take_screenshot tool returns the image as base64-encoded data, not a binary PNG. When the agent writes that base64 text directly into a .png file, the file is corrupted and your OS reports it cannot be opened. Fix: decode the base64 payload before saving.
Option 1 – prompt the agent explicitly: "Use mobile_take_screenshot, then decode the base64 result and write the binary data to /path/to/screenshot.png."
Option 2 – decode manually from the terminal:
- Linux/macOS: base64 -d screenshot.txt > screenshot.png
- Python: python3 -c "import base64; open('screenshot.png','wb').write(base64.b64decode(open('screenshot.txt').read()))"
If the saved content starts with data:image/png;base64,, strip that prefix before decoding. After decoding, the PNG will open normally in any image viewer.