mobile-next/mobile-mcp 来源: https://github.com/mobile-next/mobile-mcp # Mobile Next - 面向移动开发与自动化的 MCP 服务器 | iOS、Android、模拟器、仿真器及真机 英文 | 日本語 | 简体中文 这是一个 MCP 服务器，通过平台无关的接口实现可扩展的移动自动化与开发，无需分别掌握 iOS 或 Android 知识。您可以在仿真器、模拟器和真机（iOS 和 Android）上运行它。该服务器允许智能体和大语言模型通过结构化的无障碍快照或基于截图的坐标点击，与原生的 iOS/Android 应用和设备进行交互。 兼容 Claude Code、Codex、Gemini、GitHub Copilot、Antigravity —— 或任何支持 MCP 的客户端。 可以在您的本地设备上运行，也可以通过 Mobile Next Cloud (https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=intro) 连接到云端的 iOS 和 Android 真机使用——相同的工具，无需本地设置。 https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde ### 主要用例 我们如何帮助扩展移动自动化： - 📲 用于测试或数据录入场景的原生应用自动化（iOS 和 Android）。 - 📝 无需手动控制模拟器/仿真器或真机（iPhone、三星、谷歌 Pixel 等）即可编写脚本化流程和表单交互。 - 🧭 由大语言模型驱动的自动化多步骤用户旅程。 - 👆 面向智能体框架的通用移动应用程序交互。 - 🤖 支持智能体之间的通信，用于移动自动化用例和数据提取。 ## 主要功能 - 🚀 无障碍优先——快速且低成本：直接从原生无障碍树驱动应用（无需视觉模型，无需图像令牌），仅在必要时回退到截图+坐标方式。 - 📱 一个 API，覆盖所有目标：相同的工具适用于 iOS 和 Android——模拟器、仿真器和真机。 - 🧠 无需平台专业知识：无需 XCUITest，无需 Espresso，无需特定平台的胶水代码——只需描述目标，智能体就能完成。 - 🧰 完整的设备控制：点击、滑动、手势；应用安装/启动/终止；屏幕录制；硬件按键；深度链接；屏幕方向。 - 📊 结构化、确定性的输出：读取真实 UI 元素并提取结构化数据，消除了仅依赖截图方法的模糊性。 ### 🎯 平台支持 | 目标 | 支持 | 设置 | |—|:—:|—| | 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_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 - 使用 Bundle ID 或包名卸载应用 ### 屏幕交互 - mobile_take_screenshot - 截取屏幕截图以了解屏幕内容 - mobile_save_screenshot - 将屏幕截图保存到文件 - mobile_list_elements_on_screen - 列出屏幕上的 UI 元素及其坐标和属性 - mobile_click_on_screen_at_coordinates - 在指定的 x,y 坐标点击 - mobile_double_tap_on_screen - 在指定坐标双击 - mobile_long_press_on_screen_at_coordinates - 在指定坐标长按 - mobile_swipe_on_screen - 向任意方向滑动（上、下、左、右） - mobile_start_screen_recording - 开始录制设备屏幕为视频文件 - mobile_stop_screen_recording - 停止活动的屏幕录制并保存视频 ### 输入与导航 - mobile_type_keys - 在焦点元素中输入文本，可选提交 - mobile_press_button - 按下设备按钮（HOME、返回、音量加/减、回车等） - mobile_open_url - 在设备浏览器中打开 URL ### 日志与崩溃报告 - mobile_get_device_logs - 收集实时设备日志（Android 的 logcat，iOS 的统一日志），可选择保存到文件 - mobile_list_crashes - 列出设备上可用的崩溃报告 - mobile_get_crash - 根据 ID 获取崩溃报告的完整内容 - mobile_batch_commands - 在单次调用中按顺序运行多个工具（例如点击、输入、点击），可选在最后列出屏幕元素 ## 🏗️ Mobile MCP 架构 ## 📚 Wiki 页面 更多关于设置、配置和调试的详细信息，请查看我们的 Wiki 页面 (https://github.com/mobile-next/mobile-mcp/wiki)。 ## 前提条件 要将 MCP 与您的智能体和移动设备连接，您需要： - Xcode 命令行工具 (https://developer.apple.com/xcode/resources/) - Android 平台工具 (https://developer.android.com/tools/releases/platform-tools) - Node.js (https://nodejs.org/en/download/) v20+ - 支持 MCP (https://modelcontextprotocol.io/introduction) 的基础模型或智能体，例如 Claude MCP (https://modelcontextprotocol.io/quickstart/server)、OpenAI Agent SDK (https://openai.github.io/openai-agents-python/mcp/)、Copilot Studio (https://www.microsoft.com/en-us/microsoft-copilot/blog/copilot-studio/introducing-model-context-protocol-mcp-in-copilot-studio-simplified-integration-with-ai-apps-and-agents/) ## 安装与配置 标准配置 适用于大多数工具： json { "mcpServers": { "mobile-mcp": { "command": "npx", "args": ["-y", "@mobilenext/mobile-mcp@latest"] } } } Amp 通过 Amp VS Code 扩展设置界面添加，或更新您的 settings.json 文件： json "amp.mcpServers": { "mobile-mcp": { "command": "npx", "args": [ "@mobilenext/mobile-mcp@latest" ] } } Amp CLI： 在终端运行以下命令： bash amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest Antigravity 2 Antigravity 没有 CLI 命令来添加 MCP 服务器，因此需要手动添加。 编辑 ~/.gemini/config/mcp_config.json 并添加： json { "mcpServers": { "mobile-mcp": { "command": "npx", "args": ["-y", "@mobilenext/mobile-mcp@latest"] } } } Cline 要设置 Cline，只需将上述 JSON 添加到您的 MCP 设置文件中。更多信息请参阅我们的 Wiki (https://github.com/mobile-next/mobile-mcp/wiki/Cline) Claude Code 使用 Claude Code CLI 添加 Mobile MCP 服务器： bash claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest Claude Desktop 请遵循 MCP 安装指南 (https://modelcontextprotocol.io/quickstart/user)，使用上述 JSON 配置。 Codex 使用 Codex CLI 添加 Mobile MCP 服务器： bash codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest" 或者，创建或编辑配置文件 ~/.codex/config.toml 并添加： toml [mcp_servers.mobile-mcp] command = "npx" args = ["@mobilenext/mobile-mcp@latest"] 更多信息，请参阅 Codex MCP 文档。 Copilot 使用 Copilot CLI 交互式添加 Mobile MCP 服务器： text /mcp add 您可以编辑配置文件 ~/.copilot/mcp-config.json 并添加： 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 服务器： bash gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest Goose #### 点击按钮安装： 在 Goose 中安装 (https://goose-docs.ai/extension?cmd=npx&arg=-y&arg=%40mobilenext%2Fmobile-mcp%40latest&id=mobile-mcp&name=Mobile%20MCP&description=Mobile%20automation%20and%20development%20for%20iOS%2C%20Android%2C%20simulators%2C%20emulators%2C%20and%20real%20devices) #### 或手动安装： 前往 Advanced settings -> Extensions -> Add custom extension。 根据喜好命名，使用类型 STDIO，并将 command 设置为 npx -y @mobilenext/mobile-mcp@latest。点击 “Add Extension”。 Kiro 请遵循 MCP Servers 文档 (https://kiro.dev/docs/mcp/)。例如，在 .kiro/settings/mcp.json 中： json { "mcpServers": { "mobile-mcp": { "command": "npx", "args": [ "@mobilenext/mobile-mcp@latest" ] } } } opencode 请遵循 MCP Servers 文档。例如，在 ~/.config/opencode/opencode.json 中： json { "$schema": "https://opencode.ai/config.json", "mcp": { "mobile-mcp": { "type": "local", "command": [ "npx", "@mobilenext/mobile-mcp@latest" ], "enabled": true } } } Windsurf 打开 Windsurf 设置，导航到 MCP servers，使用 command 类型添加新服务器，命令为： bash npx @mobilenext/mobile-mcp@latest 或者如上所示，在您的设置中的 mcpServers 下添加标准配置。 阅读更多请查看我们的 Wiki (https://github.com/mobile-next/mobile-mcp/wiki)! 🚀 ### ✅ 验证其工作 服务器配置完成后，让您的智能体列出设备： > 列出可用设备 您应该会看到正在运行的模拟器、仿真器和已连接的设备。如果看到了，说明 Mobile MCP 已正确连接。如果列表为空，请确保模拟器或仿真器正在运行（参见 前提条件）——如需更多帮助，请查看 Wiki (https://github.com/mobile-next/mobile-mcp/wiki)。 ### ☁️ 扩大规模，使用云设备 想扩展到数百台设备？想在 CI/CD 流水线中使用 Mobile MCP？ 在您的智能体中输入提示词： 文本 登录 mobile next cloud，然后向我展示哪些远程设备可供我使用 ### 可流式传输 HTTP 服务器模式 默认情况下，Mobile MCP 通过 stdio 运行。要启动可流式传输 HTTP (https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) 服务器，请使用 --listen 标志： bash npx @mobilenext/mobile-mcp@latest --listen 3000 这将绑定到 localhost:3000。要绑定到特定接口： bash npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000 然后配置您的 MCP 客户端连接到 http://<您的IP>:3000/mcp（或在 TLS 后使用 https://.../mcp）。该端点接受可流式传输 HTTP（在 /mcp 上进行 POST）；远程模式是 无状态的（无需会话亲和性），这非常适合 Smithery 和其他水平托管平台。 > 迁移说明： --listen 以前在 /mcp 上提供已弃用的 HTTP+SSE 传输。客户端必须使用可流式传输 HTTP 访问 http(s)://host:port/mcp。旧的纯 SSE 流程在 /mcp 上不再可用。当绑定到 localhost 时，会自动启用 Host-header DNS 重绑定保护。 #### 授权 要在 HTTP 服务器上要求 Bearer 令牌授权，请设置 MOBILEMCP_AUTH 环境变量： bash MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000 设置后，所有请求必须包含头信息 Authorization: Bearer my-secret-token。未设置时，服务器接受未认证的连接并记录警告。 ### 🛠️ 使用方法 将 MCP 服务器添加到您的 IDE/客户端后，您可以指导您的 AI 助手使用可用的工具。例如，在 Cursor 的智能体模式下，您可以使用以下提示词来快速验证、测试和迭代 UI 交互，从屏幕读取信息，执行复杂的工作流。描述要清晰、直奔主题。 ### ✨ 示例提示词 #### 工作流 您可以在单个提示词中指定详细的工作流，验证业务逻辑，设置自动化。您可以尽情发挥： 搜索一个视频，评论、点赞并分享它。 查找由 "Way of Ramen" 发布的名为 " Beginner Recipe for Tonkotsu Ramen" 的视频，点击喜欢视频，喜欢后留下评论 " this was delicious, will make it next Friday"，然后将视频分享给您 WhatsApp 联系人列表中的第一个联系人。 下载一个成功的计步器应用，注册，设置锻炼并给应用评5星 查找并下载一个拥有超过 1k 星的免费 "Pomodoro" 应用。启动应用，用我的电子邮件注册，注册后找到如何启动番茄钟。当番茄钟开始后，回到应用商店给应用评5星，并留下评论说明该应用多么有用。 在 Substack 上搜索，阅读、高亮、评论并保存一篇文章 打开 Substack 网站，搜索 "Latest trends in AI automation 2025"，打开第一篇文章，高亮标题为 "Emerging AI trends" 的部分，将文章保存到阅读列表以便稍后复习，并对随机段落进行摘要评论。 预订一个健身课程，设置计时器 打开 ClassPass，搜索明天上午 2 英里内的瑜伽课程，预订评分最高的早上 7 点课程，确认预订，在手机上为预订的时间段设置计时器。 查找本地活动，设置日历事件 打开 Eventbrite，搜索本周末在 "Austin, TX" 举办的 AI 创业者聚会活动，选择最受欢迎的活动，注册并回复参加，设置日历事件作为提醒。 检查天气预报并发送 Whatsapp/Telegram/Slack 消息 打开天气应用，检查 "柏林" 明天的天气预报，并通过 Whatsapp/Telegram/Slack 将摘要发送给联系人 "Lauren Trown"，对他们的回复竖起大拇指。 - 在 Zoom 中安排会议并通过电子邮件分享邀请 打开 Zoom 应用，安排一个明天上午 10 点的会议，标题为 "AI Hackathon"，时长 1 小时，复制邀请链接，并通过 Gmail 发送给联系人 "[email protected]"。 ## 运行与配置 ### 环境变量 | 变量 | 描述 | 示例 | |—|—|—| | MOBILEMCP_AUTH | 在可流式传输 HTTP 服务器（--listen）上要求 Bearer 令牌——之后每个请求都必须发送 Authorization: Bearer <令牌>。 | 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 真机（需要合适的平台工具和驱动程序） 确保您已安装移动平台 SDK（Xcode、Android SDK）并正确配置。