项目简介
该 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
常见问题 (2)
故障排除为什么 @mobilenext/mobile-mcp 在工具调用失败时返回成功的 MCP 结果，而不是 isError: true？
这是 @mobilenext/mobile-mcp 1.0.8 和 1.0.9 中的一个已知 bug：共享工具处理器捕获 ActionableError 后返回的文本结果缺少 isError: true，导致 MCP 客户端将失败的操作（例如使用不存在的设备调用 mobile_get_screen_size）视为成功。修复方法：升级到包含 PR #492 的版本，在该版本中，createMcpServer() 里的处理器通过新导出的辅助函数 actionableErrorToolResult() 返回 isError: true。针对 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 };。使用 postinstall 脚本或带版本检查的 patch-package，以确保这一行修复在 npm ci 之后仍然有效。
故障排除为什么在使用 Amazon Q CLI 与 mobile-mcp 时，从 mobile_take_screenshot 保存的截图无法打开？
mobile_take_screenshot 工具返回的是 base64 编码的数据，而不是二进制 PNG。当 agent 将该 base64 文本直接写入 .png 文件时，文件会损坏，操作系统会提示无法打开。解决方法：在保存之前先解码 base64 数据。
方案一——在提示中明确告知 agent：“使用 mobile_take_screenshot，然后解码返回的 base64 结果，并将二进制数据写入 /path/to/screenshot.png。”
方案二——在终端中手动解码：
- 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 文件即可在任何图片查看器中正常打开。