Mobile Mcp

Mobile Next — 面向移动开发和自动化的 MCP 服务 | iOS、Android、模拟器、仿真器和真机

英语 | 日本語 | 简体中文

这是一个 MCP 服务，提供平台无关的接口，支持大规模移动自动化和开发，无需分别掌握 iOS 或 Android 知识。你可以在仿真器、模拟器和真机（iOS 和 Android）上运行它。

此服务让 Agent 和大模型能够通过结构化的无障碍快照，或根据屏幕截图进行坐标点击，与原生 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 等），即可执行脚本化流程和表单交互。
• 🧭 由大模型驱动的多步骤用户旅程自动化。
• 👆 面向 Agent 框架的通用移动应用交互。
• 🤖 支持 Agent 之间通信，以实现移动自动化和数据提取。

主要功能

• 🚀 无障碍优先——快速且低成本：通过原生无障碍树操作应用（无需视觉模型，也不消耗图像 token），仅在必要时才回退到截图和坐标操作。
• 📱 一个 API，适用于所有目标：相同的工具可用于 iOS 和 Android，包括模拟器和真实设备。
• 🧠 无需掌握平台专业知识：无需 XCUITest、Espresso 或针对各个平台编写胶水代码——描述目标，Agent 就会完成操作。
• 🧰 全面的设备控制：点击、滑动和手势；安装、启动和终止应用；屏幕录制；硬件按钮；深层链接；屏幕方向。
• 📊 结构化、确定性的输出：读取真实 UI 元素并提取结构化数据，减少仅依赖截图所带来的歧义。
• 🪞 在 Claude Code 中镜像设备：适用于在 Ghostty 或 kitty 中运行的 Claude Code。安装插件并运行 /mobile-mirror，即可在侧边栏中查看设备的实时屏幕，然后点击、输入并按下 Home/Back，无需离开终端。

🎯 平台支持

🔧 可用的 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 - 根据包名或 bundle ID 卸载应用

屏幕交互

• 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 URL

日志与崩溃报告

• mobile_get_device_logs - 收集设备实时日志（Android 上为 logcat，iOS 上为 unified log），可选择保存到文件
• mobile_list_crashes - 列出设备上可用的崩溃报告
• mobile_get_crash - 根据 ID 获取崩溃报告的完整内容
• mobile_batch_commands - 在一次调用中按顺序运行多个工具（例如点击、输入、点击），可选择在结束时列出屏幕元素

🏗️ Mobile MCP 架构

📚 Wiki 页面

如需了解设置、配置和调试相关问题的更多详情，请参阅我们的 wiki 页面。

前置条件

将 MCP 连接到 Agent 和移动设备所需的内容：

• Xcode 命令行工具
• Android Platform Tools
• node.js v20+
• 支持 MCP 的基础模型或 Agent，例如 Claude MCP、OpenAI Agent SDK、Copilot Studio

安装和配置

如需手动配置，以下标准配置适用于大多数工具：

{
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
    }
  }
}

"amp.mcpServers": {
  "mobile-mcp": {
    "command": "npx",
    "args": [
      "@mobilenext/mobile-mcp@latest"
    ]
  }
}

amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest

{
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
    }
  }
}

/plugin marketplace add mobile-next/mobile-mcp
/plugin install mobile-mcp@mobile-mcp

claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest

codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"

[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]

/mcp add

{
  "mcpServers": {
    "mobile-mcp": {
      "type": "local",
      "command": "npx",
      "tools": [
        "*"
      ],
      "args": [
        "@mobilenext/mobile-mcp@latest"
      ]
    }
  }
}

gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest

{
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": [
        "@mobilenext/mobile-mcp@latest"
      ]
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mobile-mcp": {
      "type": "local",
      "command": [
        "npx",
        "@mobilenext/mobile-mcp@latest"
      ],
      "enabled": true
    }
  }
}

npx @mobilenext/mobile-mcp@latest

在我们的 wiki 中了解更多！🚀

✅ 验证是否正常工作

配置好服务后，让你的 Agent 列出设备：

列出可用设备

你应该会看到正在运行的模拟器、仿真器和已连接设备。如果看到了，说明 Mobile MCP 已正确接入。如果列表为空，请确保模拟器或仿真器正在运行（参见前置要求）——如需更多帮助，请查看 wiki。

🧪 从 Agent 会话到 CI 测试

使用 Mobile MCP 自动化移动应用或测试移动应用？让你的 Agent 将流程编写为 Mobilewright 测试。这样流程将变得确定，并成为 CI/CD 工作流的一部分。

import { test, expect } from '@mobilewright/test';

test('sign in', async ({ screen }) => {
  await screen.getByLabel('Email').fill('[email protected]');
  await screen.getByRole('button', { name: 'Sign In' }).tap();
  await expect(screen.getByText('Welcome back')).toBeVisible();
});

从 npm init mobilewright@latest 开始。

☁️ 扩大规模，使用云设备

想要将规模扩展到数百台设备？想在 CI/CD 流水线中使用 Mobile MCP？

在你的 Agent 中，输入提示词：

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 传输。客户端必须使用 Streamable HTTP 连接 http(s)://host:port/mcp。旧的 /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。未设置时，服务会接受未经身份验证的连接，并记录警告。

🛠️ 使用方法

将 MCP 服务添加到 IDE/客户端后，你可以指示 AI 助手使用可用工具。 例如，在 Cursor 的 Agent 模式下，你可以使用以下提示词，快速验证、测试并迭代 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 "[email protected]".

运行与配置

环境变量

模拟器、仿真器和真实设备

启动后，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 上：

1. 启动仿真器（avdmanager / emulator 命令）。
2. 使用所需标志运行 Mobile MCP。

在 iOS 上，你需要安装 Xcode，并在通过 Mobile MCP 使用该模拟器实例前启动 Simulator。

• xcrun simctl list
• xcrun simctl boot "iPhone 16"

🧩 Mobile Next 生态的一部分

Mobile MCP 是一套用于操控真实移动设备的工具包中的一部分：

• mobilewright — “移动端的 Playwright”。准备好将 Agent 驱动的探索转化为 iOS 和 Android 上可重复、确定性的测试后，就可以升级到 mobilewright。
• mobilecli — Mobile MCP 基于其构建的通用设备命令行工具：通过命令行或 JSON-RPC API 控制设备、模拟器和仿真器。
• Mobile Next Cloud — 同一套技术栈，按需租用：随时可用的真实 iOS 和 Android 设备。只需向 Agent 输入提示词：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。