Claude In Mobile

🚀 Claude Mobile

Claude Mobile 是一款用于移动和桌面自动化的 MCP 服务器，支持 Android（通过 ADB）、iOS 模拟器（通过 simctl）、桌面（Compose Multiplatform）和 Aurora OS（通过 audb）。它就像 Claude in Chrome 一样，但适用于移动设备和桌面应用程序。你可以通过 Claude 使用自然语言控制你的 Android 手机、模拟器、iOS 模拟器、桌面应用程序或 Aurora OS 设备。

🚀 快速开始

Claude Mobile 允许你通过自然语言控制多种平台的设备和应用程序。通过简单的命令，你可以执行诸如列出设备、截图、点击、输入文本等操作。

✨ 主要特性

• 统一 API：相同的命令适用于 Android、iOS、桌面和 Aurora OS。
• 智能截图：自动压缩以实现最佳的大语言模型处理（不再有过大的图像！）
• 带注释的截图：带有彩色边界框和编号元素标签的截图，便于直观理解 UI。
• 权限管理：以编程方式授予、撤销和重置应用程序权限（Android 运行时权限、iOS 隐私服务）。
• 设备日志：通过过滤器读取 logcat/系统日志以进行调试。
• UI 交互：通过坐标或元素文本进行点击、长按、滑动操作。
• 文本输入：在聚焦字段中输入文本。
• 应用控制：启动、停止和安装应用程序。
• 平台选择：明确指定目标平台为 Android、iOS、桌面或 Aurora OS。
• 桌面支持：通过窗口管理、剪贴板和性能指标测试 Compose Multiplatform 桌面应用程序。

📦 安装指南

一键安装（适用于任何客户端）

使用 add-mcp 可自动检测已安装的客户端：

npx add-mcp claude-in-mobile -y

或者指定特定的客户端：

npx add-mcp claude-in-mobile -a claude-code -y
npx add-mcp claude-in-mobile -a opencode -y
npx add-mcp claude-in-mobile -a cursor -y

Claude Code CLI

claude mcp add --transport stdio mobile -- npx -y claude-in-mobile

若要全局添加（在所有项目中可用）：

claude mcp add --scope user --transport stdio mobile -- npx -y claude-in-mobile

OpenCode

使用交互式设置：

opencode mcp add

或者手动添加到 opencode.json（项目根目录或 ~/.config/opencode/opencode.json）：

{
  "mcp": {
    "mobile": {
      "type": "local",
      "command": ["npx", "-y", "claude-in-mobile"],
      "enabled": true
    }
  }
}

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "mobile": {
      "command": "npx",
      "args": ["-y", "claude-in-mobile"]
    }
  }
}

任何 MCP 客户端

打印适用于你的客户端的配置片段：

npx claude-in-mobile --init <client-name>
# 支持的客户端：opencode, cursor, claude-code

从 npm 安装

npx claude-in-mobile

从源代码安装

git clone https://github.com/AlexGladkov/claude-in-mobile.git
cd claude-in-mobile
npm install
npm run build:all  # 构建 TypeScript + 桌面配套应用

注意：若要支持桌面应用，你需要运行 npm run build:desktop（或 build:all）来编译桌面配套应用。

使用本地构建版本与 MCP 客户端配合

从源代码构建后，将你的 MCP 客户端指向本地的 dist/index.js，而不是使用 npx：

{
  "mcpServers": {
    "mobile": {
      "command": "node",
      "args": ["/path/to/claude-in-mobile/dist/index.js"]
    }
  }
}

对于 OpenCode（opencode.json）：

{
  "mcp": {
    "mobile": {
      "type": "local",
      "command": ["node", "/path/to/claude-in-mobile/dist/index.js"],
      "enabled": true
    }
  }
}

手动配置

添加到你的 Claude Code 设置（~/.claude.json 或项目设置）：

{
  "mcpServers": {
    "mobile": {
      "command": "npx",
      "args": ["-y", "claude-in-mobile"]
    }
  }
}

Windows 系统

claude mcp add --transport stdio mobile -- cmd /c npx -y claude-in-mobile

🔧 技术细节

系统要求

Android

• 已安装 ADB 并将其添加到系统路径。
• 已连接的 Android 设备（启用 USB 调试）或模拟器。

iOS

• 安装了 Xcode 的 macOS 系统。
• iOS 模拟器（目前暂不支持物理设备）。
• 若要进行完整的 UI 检查和基于元素的交互，需要 WebDriverAgent：

  npm install -g appium
  appium driver install xcuitest
  

  或者将 WDA_PATH 环境变量设置为自定义的 WebDriverAgent 位置。

桌面

• macOS 系统（计划支持 Windows/Linux）。
• 用于构建桌面配套应用的 JDK 17+。
• 待测试的 Compose Multiplatform 桌面应用程序。

Aurora OS

• 已安装 audb CLI 并将其添加到系统路径（cargo install audb-client）。
• 已连接且启用 SSH 的 Aurora OS 设备。
• 设备上需要安装 Python 以支持点击/滑动操作：devel-su pkcon install python。

可用工具

核心工具（适用于所有平台）

桌面特定工具

有关详细的桌面 API 文档，请参阅 Desktop Specification

💻 使用示例

基础用法

只需自然地与 Claude 对话：

"Show me all connected devices"
"Take a screenshot of the Android emulator"
"Take a screenshot on iOS"
"Tap on Settings"
"Swipe down to scroll"
"Type 'hello world' in the search field"
"Press the back button on Android"
"Open Safari on iOS"
"Switch to iOS simulator"
"Run the app on both platforms"

权限管理

"Grant camera permission to com.example.app on Android"
"Revoke location access from com.example.app"
"Reset all permissions for com.apple.Maps on iOS"

带注释的截图

"Take an annotated screenshot"  → 带有绿色（可点击）和红色（不可点击）边界框 + 编号元素索引的截图

平台选择

你可以明确指定平台：

"Screenshot on android"     → 使用 Android 设备
"Screenshot on ios"         → 使用 iOS 模拟器
"Screenshot on desktop"     → 使用桌面应用程序
"Screenshot on aurora"      → 使用 Aurora OS 设备
"Screenshot"                → 使用最后活动的设备

或者设置活动设备：

"Use the iPhone 15 simulator"
"Switch to the Android emulator"
"Switch to desktop"
"Switch to Aurora device"

桌面示例

"Launch my desktop app from /path/to/app"
"Take a screenshot of the desktop app"
"Get window info"
"Resize window to 1280x720"
"Tap at coordinates 100, 200"
"Get clipboard content"
"Set clipboard to 'test text'"
"Get performance metrics"
"Stop the desktop app"

Aurora 示例

"List all Aurora devices"
"Take a screenshot on Aurora"
"Tap at coordinates 100, 200 on Aurora"
"Launch ru.example.app on Aurora"
"List installed apps on Aurora device"
"Get logs from Aurora device"
"Push file.txt to /home/defaultuser/ on Aurora device"

原生 CLI

这是一个 2 MB 的原生 Rust 二进制文件，包含所有相同的命令，无需 Node.js 和依赖项。

安装 CLI

brew tap AlexGladkov/claude-in-mobile
brew install claude-in-mobile

或者从 Releases 下载。

与 MCP 相比的优势

• 易于安装：使用 brew install 或复制单个 2 MB 的二进制文件。
• 无依赖项：无需 Node.js、npm 等。
• 可从终端使用：直接运行命令，无需 Claude Code 或 MCP 客户端。
• 测试自动化：编写适用于任何平台的通用 .sh 脚本，无需了解平台内部机制。
• 节省令牌：仅在使用时加载技能文档；MCP 在每个请求中加载所有工具模式，在会话中会快速累积。
• 速度快：命令启动时间约为 5ms（Rust），而 Node.js MCP 约为 500ms。
• 适用于 CI/CD：具有退出代码、标准输出/错误输出，可在任何环境中运行。

测试脚本示例

#!/bin/bash
claude-in-mobile launch android com.example.app
claude-in-mobile wait 2000
claude-in-mobile tap android 0 0 --text "Login"
claude-in-mobile input android "test@example.com"
claude-in-mobile screenshot android -o result.png
claude-in-mobile ui-dump android | grep "Welcome" && echo "PASS" || echo "FAIL"

Claude Code 插件

claude plugin marketplace add AlexGladkov/claude-in-mobile
claude plugin install claude-in-mobile@claude-in-mobile

安装后，Claude Code 可以使用自然语言控制设备。技能仅在需要时加载到上下文中，不使用时不会产生令牌开销。

有关完整的 CLI 文档，请参阅 cli/README.md。

iOS WebDriverAgent 设置

若要进行完整的 iOS UI 检查和基于元素的交互，需要 WebDriverAgent。它支持以下功能：

• get_ui - JSON 可访问性树检查
• 使用 label 或 text 参数的 tap - 基于元素的点击
• find_element - 元素发现和查询
• swipe - 改进的手势模拟

安装

自动安装（通过 Appium）：

npm install -g appium
appium driver install xcuitest

手动安装： 将 WDA_PATH 环境变量设置为你的 WebDriverAgent 位置：

export WDA_PATH=/path/to/WebDriverAgent

首次使用

首次使用时，WebDriverAgent 将自动执行以下操作：

1. 从 Appium 安装或 WDA_PATH 中发现。
2. 使用 xcodebuild 进行构建（一次性，约 2 分钟）。
3. 在 iOS 模拟器上启动。
4. 通过端口 8100+ 的 HTTP 连接。

故障排除

构建失败：

# 安装 Xcode 命令行工具
xcode-select --install

# 接受许可协议
sudo xcodebuild -license accept

# 设置 Xcode 路径
sudo xcode-select -s /Applications/Xcode.app

会话失败：

• 确保模拟器已启动：xcrun simctl list | grep Booted
• 检查端口可用性：lsof -i :8100
• 尝试重启模拟器

手动测试：

cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
xcodebuild test -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'platform=iOS Simulator,id=<DEVICE_UDID>'

工作原理

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ Claude Code │────▶│                  │────▶│  Android (ADB)  │
├─────────────┤     │  Claude Mobile   │     └─────────────────┘
│  OpenCode   │────▶│   MCP Server     │     ┌─────────────────┐
├─────────────┤     │                  │────▶│ iOS (simctl+WDA)│
│   Cursor    │────▶│  (auto-detects   │     └─────────────────┘
├─────────────┤     │   client via     │     ┌─────────────────┐
│  Any MCP    │────▶│   MCP protocol)  │────▶│ Desktop (Compose)│
│   Client    │     │                  │     └─────────────────┘
└─────────────┘     │                  │     ┌─────────────────┐
                    │                  │────▶│ Aurora (audb)   │
                    └──────────────────┘     └─────────────────┘

1. Claude 通过 MCP 协议发送命令。
2. 服务器将命令路由到适当的平台（ADB、simctl+WDA、桌面配套应用或 audb）。
3. 命令在你的设备或桌面应用程序上执行。
4. 结果（截图、UI 数据、指标）返回给 Claude。

📄 许可证

本项目采用 MIT 许可证。