# https://github.com/mobile-next/mobile-mcp 项目说明书
生成时间：2026-05-15 10:52:12 UTC
## 目录
- [Overview](#overview)
- [Installation and Configuration](#installation)
- [Prerequisites](#prerequisites)
- [System Architecture](#system-architecture)
- [Device Abstraction Layer](#device-abstraction)
- [MCP Tools Reference](#mcp-tools-reference)
- [Device Management](#device-management)
- [App Management](#app-management)
- [Screen Interaction and Input](#screen-interaction)
- [iOS Implementation](#ios-implementation)
## Overview
### 相关页面
相关主题：[Installation and Configuration](#installation), [System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
- [CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)
# Overview
Mobile MCP (Model Context Protocol) is an open-source project that enables AI assistants to interact with mobile devices through the MCP protocol. It provides a bridge between AI agents and mobile device automation, supporting both iOS and Android platforms including simulators, emulators, and physical devices.
资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
## Project Purpose
The project serves as an MCP server implementation that allows AI assistants to:
- Automate native iOS and Android applications for testing or data entry scenarios
- Execute scripted flows and form interactions without manual device control
- Automate multi-step user journeys driven by large language models
- Enable general-purpose mobile application interaction for agent-based frameworks
- Facilitate agent-to-agent communication for mobile automation use cases and data extraction
资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
## Core Architecture
Mobile MCP follows a modular architecture that separates platform-specific implementations from the core server logic.
```mermaid
graph TD
subgraph "MCP Clients"
C1[Claude Desktop]
C2[Cursor]
C3[VS Code]
C4[Codex]
C5[Other MCP Clients]
end
subgraph "Mobile MCP Server"
Server[Core Server
src/server.ts]
Tools[MCP Tools Layer]
Robot[Robot Interface
src/robot.ts]
end
subgraph "Platform Implementations"
iOS_WDA[WebDriver Agent
src/webdriver-agent.ts]
iOS_Sim[iOS Simulator
src/iphone-simulator.ts]
Android[Android Device Manager]
end
subgraph "Target Devices"
iOS_Real[iOS Physical Device]
Android_Real[Android Physical Device]
Simulators[iOS Simulators]
Emulators[Android Emulators]
end
C1 & C2 & C3 & C4 & C5 --> Server
Server --> Tools
Tools --> Robot
Robot --> iOS_WDA & iOS_Sim & Android
iOS_WDA --> iOS_Real & Simulators
iOS_Sim --> Simulators
Android --> Android_Real & Emulators
```
### Key Components
| Component | File | Purpose |
|-----------|------|---------|
| Core Server | `src/server.ts` | MCP protocol implementation, device management, tool routing |
| Robot Interface | `src/robot.ts` | Abstract interface defining device interaction methods |
| WebDriver Agent | `src/webdriver-agent.ts` | iOS real device and simulator automation via WebDriverAgent |
| iOS Simulator | `src/iphone-simulator.ts` | Direct iOS simulator control using simctl |
| Android Manager | (platform-specific) | Android device automation |
资料来源：[src/server.ts:1-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
## Device Detection Flow
The server implements a device detection mechanism that identifies the platform type when a device ID is provided.
```mermaid
graph TD
Start[Get Device ID] --> Check_iOS{iOS Device?}
Check_iOS -->|Yes| Return_iOS[Return IosRobot]
Check_iOS -->|No| Check_Android{Android Device?}
Check_Android -->|Yes| Return_Android[Return AndroidRobot]
Check_Android -->|No| Check_Simulator{iOS Simulator?}
Check_Simulator -->|Yes| Return_Simulator[Return Simulator Robot]
Check_Simulator -->|No| Error[Throw Error]
style Return_iOS fill:#90EE90
style Return_Android fill:#90EE90
style Return_Simulator fill:#90EE90
style Error fill:#FFB6C1
```
资料来源：[src/server.ts:20-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
## Available Tools
Mobile MCP exposes the following tool categories through the MCP protocol:
### Device Management
| Tool | Description |
|------|-------------|
| `mobile_list_available_devices` | List all available devices (simulators, emulators, and real devices) |
| `mobile_get_screen_size` | Get screen dimensions in pixels |
| `mobile_get_orientation` | Get current screen orientation |
| `mobile_set_orientation` | Change screen orientation (portrait/landscape) |
### App Management
| Tool | Description |
|------|-------------|
| `mobile_list_apps` | List all installed apps on the device |
| `mobile_launch_app` | Launch an app using package name |
| `mobile_terminate_app` | Stop and terminate a running app |
| `mobile_install_app` | Install an app from file (.apk, .ipa, .app, .zip) |
| `mobile_uninstall_app` | Uninstall an app using bundle ID or package name |
### Screen Interaction
| Tool | Description |
|------|-------------|
| `mobile_take_screenshot` | Capture screenshot to understand screen content |
| `mobile_save_screenshot` | Save screenshot to a file |
| `mobile_list_elements_on_screen` | List UI elements with coordinates and properties |
| `mobile_click_on_screen_at_coordinates` | Click at specific x,y coordinates |
| `mobile_double_tap_on_screen` | Double-tap at specific coordinates |
| `mobile_long_press_on_screen_at_coordinates` | Long press at specific coordinates |
| `mobile_swipe_on_screen` | Swipe in any direction (up, down, left, right) |
### Input & Navigation
| Tool | Description |
|------|-------------|
| `mobile_type_keys` | Type text into focused elements with optional submit |
| `mobile_press_button` | Press device buttons (home, back, etc.) |
资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
## Robot Interface
The `Robot` interface defines the contract for all platform implementations:
```typescript
interface Robot {
// Screen operations
getScreenshot(): Promise;
getScreenSize(): Promise;
getOrientation(): Promise;
setOrientation(orientation: Orientation): Promise;
// Element operations
getElementsOnScreen(): Promise;
// Touch operations
tap(x: number, y: number): Promise;
doubleTap(x: number, y: number): Promise;
longPress(x: number, y: number, duration: number): Promise;
swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;
// Text and keys
sendKeys(text: string): Promise;
pressButton(button: Button): Promise;
// App management
listApps(): Promise;
launchApp(packageName: string, locale?: string): Promise;
terminateApp(packageName: string): Promise;
installApp(path: string): Promise;
uninstallApp(bundleId: string): Promise;
// URL handling
openUrl(url: string): Promise;
}
```
资料来源：[src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
## Platform Support
### iOS Platform
iOS automation is handled through two mechanisms:
1. **WebDriverAgent** (`src/webdriver-agent.ts`): Used for real iOS devices and Xcode-managed simulators
- Communicates via HTTP with WDA session
- Filters elements by accepted types: `TextField`, `Button`, `Switch`, `Icon`, `SearchField`, `StaticText`, `Image`
- Uses element visibility and accessibility properties for filtering
2. **iOS Simulator** (`src/iphone-simulator.ts`): Direct simctl control for booted simulators
- Handles `.app` bundle installation
- Supports `.zip` file extraction with zip-slip vulnerability protection
- Uses simctl command-line tool
资料来源：[src/webdriver-agent.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
### Android Platform
Android automation uses platform-specific managers to:
- List connected devices
- Query UI elements via accessibility tree
- Execute touch and input operations
- Manage app lifecycle
## Communication Modes
### STDIO Mode (Default)
The server communicates over standard input/output:
```bash
npx -y @mobilenext/mobile-mcp@latest
```
### SSE Server Mode
For HTTP-based connections, the server can listen on a specified port:
```bash
npx @mobilenext/mobile-mcp@latest --listen 3000
```
Optional Bearer token authentication can be enabled:
```bash
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
## Technology Stack
| Component | Technology | Version |
|-----------|------------|---------|
| Runtime | Node.js | >=18 |
| MCP SDK | @modelcontextprotocol/sdk | 1.26.0 |
| HTTP Framework | express | 5.1.0 |
| CLI Framework | commander | 14.0.0 |
| Validation | zod | 4.1.13 |
| XML Parsing | fast-xml-parser | 5.5.7 |
| Native CLI | mobilecli | 0.3.70 (optional) |
资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)
## Key Features
- **Fast and lightweight**: Uses native accessibility trees for most interactions, or screenshot-based coordinates where accessibility labels are not available
- **LLM-friendly**: No computer vision model required in Accessibility (Snapshot)
- **Visual Sense**: Evaluates and analyses what's actually rendered on screen
- **Cross-platform**: Supports iOS, Android, simulators, emulators, and real devices
- **Standard protocol**: Built on Model Context Protocol for seamless AI assistant integration
资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
## Version History
The project follows semantic versioning with active development:
| Version | Date | Key Changes |
|---------|------|-------------|
| 0.0.49 | 2026-03-24 | Path traversal fix in save screenshot and record video |
| 0.0.48 | 2026-03-20 | fast-xml-parser security updates, error handling fixes |
| 0.0.47 | 2026-03-09 | Zod coerce for number parameter parsing, locale support for iOS |
| 0.0.42 | 2026-02-03 | mobilecli upgrade, fast-xml-parser security update |
| 0.0.41 | 2026-01-27 | Android element filtering improvements |
资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)
## Getting Started
### Installation
Add to your MCP client configuration:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
### Prerequisites
- Node.js >= 18
- For iOS: Xcode Command Line Tools, WebDriverAgent (for real devices)
- For Android: Android SDK, ADB configured
### Client Support
Mobile MCP is compatible with multiple AI coding assistants:
- Claude Desktop
- Claude Code
- Cursor
- VS Code
- Codex
- Copilot
- Gemini CLI
- Goose
- Cline
- Windsurf
- Qodo Gen
- Amp
- Kiro
- opencode
资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
---
## Installation and Configuration
### 相关页面
相关主题：[Overview](#overview), [Prerequisites](#prerequisites)
Relevant Source Files
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
- [server.json](https://github.com/mobile-next/mobile-mcp/blob/main/server.json)
- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)
# Installation and Configuration
## Overview
Mobile MCP is a Model Context Protocol (MCP) server that enables mobile automation for iOS and Android devices. The server provides a standardized interface for AI assistants to interact with mobile devices through simulators, emulators, and real hardware.
This page covers the complete installation process, configuration options, and server deployment modes.
## Prerequisites
### System Requirements
| Requirement | Specification |
|-------------|---------------|
| Node.js | Version 18 or higher |
| Package Manager | npm, yarn, or pnpm |
| Mobile CLI Tools | `mobilecli` (auto-installed as optional dependency) |
| Platform Tools | Xcode Command Line Tools (iOS) / Android SDK (Android) |
The server requires Node.js 18+ as specified in `package.json`:
```json
"engines": {
"node": ">=18"
}
```
资料来源：[package.json:12]()
### Required Mobile Tools
Mobile MCP depends on `mobilecli` for device communication. The SDK checks for mobilecli availability at server startup:
```typescript
const ensureMobilecliAvailable = (): void => {
try {
const version = mobilecli.getVersion();
if (version.startsWith("failed")) {
throw new Error("mobilecli version check failed");
}
} catch (error: any) {
throw new ActionableError(`mobilecli is not available or not working properly...`);
}
};
```
资料来源：[src/server.ts:1-20]()
## Installation Methods
### Standard NPM Installation
The recommended installation method uses npx to run the package directly:
```bash
npx -y @mobilenext/mobile-mcp@latest
```
This command downloads and executes the latest version without requiring local installation.
### Local Installation
For development or customization, install locally:
```bash
npm install @mobilenext/mobile-mcp
```
The package provides a binary entry point:
```json
"bin": {
"mcp-server-mobile": "lib/index.js"
}
```
资料来源：[package.json:62-65]()
### Building from Source
To build from source:
```bash
git clone https://github.com/mobile-next/mobile-mcp.git
cd mobile-mcp
npm install
npm run build
```
Build artifacts are output to the `lib/` directory:
```bash
npm run build # Compiles TypeScript and sets executable permissions
npm run watch # Watch mode for development
```
资料来源：[package.json:22-30]()
## Server Configuration
### Standard MCP Configuration
The following JSON configuration works across most MCP clients:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
资料来源：[README.md:1]()
### Configuration Schema
The server adheres to the MCP protocol schema:
```json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.mobile-next/mobile-mcp",
"description": "MCP server for iOS and Android Mobile Development, Automation and Testing",
"version": "{{VERSION}}",
"packages": [
{
"registryType": "npm",
"registryBaseUrl": "https://registry.npmjs.org",
"identifier": "@mobilenext/mobile-mcp",
"transport": {
"type": "stdio"
}
}
]
}
```
资料来源：[server.json:1-20]()
## Client-Specific Configuration
### Claude Code
```bash
claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
```
资料来源：[README.md:1]()
### Claude Desktop
Follow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user) and use the standard JSON configuration above.
### Codex
**CLI Installation:**
```bash
codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
```
**Manual Configuration** (`~/.codex/config.toml`):
```toml
[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]
```
资料来源：[README.md:1]()
### Copilot
Configuration file (`~/.copilot/mcp-config.json`):
```json
{
"mcpServers": {
"mobile-mcp": {
"type": "local",
"command": "npx",
"tools": ["*"],
"args": ["@mobilenext/mobile-mcp@latest"]
}
}
}
```
资料来源：[README.md:1]()
### Cursor
**Installation Button:**
Click the provided deeplink or navigate to `Cursor Settings` → `MCP` → `Add new MCP Server`.
**Manual Configuration:**
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["@mobilenext/mobile-mcp@latest"]
}
}
}
```
资料来源：[README.md:1]()
### Gemini CLI
```bash
gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
```
资料来源：[README.md:1]()
### Goose
**UI Installation:**
Use the extension install button or navigate to `Advanced settings` → `Extensions` → `Add custom extension`.
**Manual Configuration:**
- Type: `STDIO`
- Command: `npx -y @mobilenext/mobile-mcp@latest`
资料来源：[README.md:1]()
### Windsurf
Navigate to Windsurf settings → `MCP servers` → Add new server:
```bash
npx @mobilenext/mobile-mcp@latest
```
资料来源：[README.md:1]()
### Amp
**CLI Installation:**
```bash
amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
```
**VS Code Extension:**
Add via settings.json:
```json
"amp.mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["@mobilenext/mobile-mcp@latest"]
}
}
```
资料来源：[README.md:1]()
### Cline
Add the standard JSON configuration to your MCP settings file.
资料来源：[README.md:1]()
### Kiro
Configuration file (`~/.kiro/settings/mcp.json`):
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["@mobilenext/mobile-mcp@latest"]
}
}
}
```
资料来源：[README.md:1]()
### opencode
Configuration file (`~/.config/opencode/opencode.json`):
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mobile-mcp": {
"type": "local",
"command": ["npx", "@mobilenext/mobile-mcp@latest"],
"enabled": true
}
}
}
```
资料来源：[README.md:1]()
### Qodo Gen
Open Qodo Gen chat panel → `Connect more tools` → `+ Add new MCP` → Paste the standard configuration.
资料来源：[README.md:1]()
## SSE Server Mode
By default, Mobile MCP communicates over stdio. For remote or web-based deployments, enable SSE (Server-Sent Events) mode.
### Starting the SSE Server
**Basic Usage:**
```bash
npx @mobilenext/mobile-mcp@latest --listen 3000
```
**Binding to Specific Interface:**
```bash
npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000
```
This binds the server to all network interfaces on port 3000.
### Client Configuration for SSE
Configure your MCP client to connect to the SSE endpoint:
```
http://:3000/mcp
```
### Architecture Diagram
```mermaid
graph TD
A[MCP Client] -->|HTTP/MCP Protocol| B[SSE Server]
B --> C{Mobile MCP Server}
C -->|iOS Devices| D[IosRobot]
C -->|Android Devices| E[AndroidRobot]
D --> F[mobilecli]
E --> F
F --> G[iOS Simulator/Device]
F --> H[Android Emulator/Device]
```
## Authorization
When running in SSE mode, secure the server with Bearer token authentication.
### Configuration
Set the `MOBILEMCP_AUTH` environment variable:
```bash
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
### Client Request Format
All requests must include the authorization header:
```
Authorization: Bearer my-secret-token
```
## Dependencies
### Production Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| @modelcontextprotocol/sdk | 1.26.0 | MCP protocol implementation |
| ajv | ^8.18.0 | JSON schema validation |
| commander | 14.0.0 | CLI argument parsing |
| express | 5.1.0 | SSE server framework |
| fast-xml-parser | 5.5.7 | XML parsing for mobile protocols |
| qs | ^6.15.0 | Query string parsing |
| zod | ^4.1.13 | Schema validation |
| zod-to-json-schema | 3.25.0 | Zod to JSON Schema conversion |
| mobilecli | 0.3.70 | Mobile device communication (optional) |
资料来源：[package.json:31-48]()
### Dev Dependencies
Key development dependencies include:
- TypeScript 5.8.2
- ESLint 9.19.0
- Mocha 11.1.0 (testing)
- ts-node 10.9.2
- husky 9.1.7 (git hooks)
资料来源：[package.json:49-60]()
## Troubleshooting
### mobilecli Not Available
If the server fails to start with "mobilecli is not available":
1. Ensure the optional dependency is installed:
```bash
npm install mobilecli
```
2. Verify installation:
```bash
mobilecli --version
```
3. Check platform compatibility using the binary resolution logic in `src/mobilecli.ts`.
### Binary Resolution Path
The server searches for mobilecli in this order:
```mermaid
graph TD
A[Start] --> B{Current path contains node_modules?}
B -->|Yes| C[Find last node_modules directory]
C --> D[Check mobilecli/bin/]
D --> E{Binary exists?}
E -->|Yes| F[Return path]
E -->|No| G[Check parentDir/node_modules/mobilecli/bin/...]
B -->|No| G
G --> H{Binary exists?}
H -->|Yes| F
H -->|No| I[Throw error]
```
资料来源：[src/mobilecli.ts:1-35]()
### Node.js Version
Ensure Node.js 18+ is installed:
```bash
node --version
```
### iOS Simulator Issues
For iOS simulators, ensure Xcode Command Line Tools are installed:
```bash
xcode-select --install
```
List available simulators:
```bash
xcrun simctl list
```
Boot a simulator before use:
```bash
xcrun simctl boot "iPhone 16"
```
## Next Steps
After successful installation:
1. **Connect a Device**: Use physical devices, simulators (iOS), or emulators (Android)
2. **Verify Connection**: Run `mobile_list_devices` tool
3. **Take a Screenshot**: Use `mobile_take_screenshot` to verify communication
4. **Explore Tools**: Review available tools in the [main documentation](https://github.com/mobile-next/mobile-mcp/wiki)
---
## Prerequisites
### 相关页面
相关主题：[Installation and Configuration](#installation), [iOS Implementation](#ios-implementation)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)
- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
# Prerequisites
Mobile MCP (Model Context Protocol) enables AI agents to interact with mobile devices for automation, testing, and mobile application manipulation. Before using Mobile MCP, you must ensure your environment meets the necessary requirements for both the MCP server and the target mobile devices.
## System Requirements
### Node.js Environment
Mobile MCP requires **Node.js version 18 or higher**. This requirement is enforced through the `package.json` engine specification:
```json
"engines": {
"node": ">=18"
}
```
资料来源：[package.json:11]()
The MCP SDK version 1.26.0 is used as the core protocol implementation, which also requires a modern Node.js environment with support for ES modules and async/await patterns.
### Supported Platforms
Mobile MCP supports automation across multiple platform types:
| Platform Type | Examples | Access Method |
|---------------|----------|---------------|
| iOS Simulators | iPhone Simulator, iPad Simulator | Local Xcode tools |
| iOS Real Devices | Physical iPhones, iPads | WebDriverAgent via tunnel |
| Android Emulators | Android Studio Emulator, Genymotion | ADB |
| Android Real Devices | Samsung, Google Pixel, etc. | ADB |
资料来源：[src/server.ts:32-55]()
The server automatically detects which platform type a device belongs to by checking against iOS devices, Android devices, and iOS simulators in sequence.
## Required Software Components
### mobilecli
The `mobilecli` package is the core CLI tool that Mobile MCP relies on for device communication. It is listed as an **optional dependency** in `package.json`:
```json
"optionalDependencies": {
"mobilecli": "0.3.70"
}
```
资料来源：[package.json:31-33]()
The server performs a version check on startup to ensure `mobilecli` is available:
```typescript
const ensureMobilecliAvailable = (): void => {
try {
const version = mobilecli.getVersion();
if (version.startsWith("failed")) {
throw new Error("mobilecli version check failed");
}
} catch (error: any) {
throw new ActionableError(`mobilecli is not available or not working properly.`);
}
};
```
资料来源：[src/server.ts:18-28]()
### Installation Methods
#### Via npm (Recommended)
```bash
npx @mobilenext/mobile-mcp@latest
```
#### Via mobilecli package
```bash
npm install -g mobilecli
```
## iOS-Specific Prerequisites
### WebDriverAgent (Real Devices)
For physical iOS devices, **WebDriverAgent (WDA)** must be installed and running. WDA is Facebook's WebDriver protocol implementation for iOS used for device control and element inspection.
The `IosManager` class manages WDA connections:
```typescript
private async wda(): Promise {
await this.assertTunnelRunning();
if (!(await this.isWdaForwardRunning())) {
throw new ActionableError("Port forwarding to WebDriverAgent is not running");
}
const wda = new WebDriverAgent("localhost", WDA_PORT);
if (!(await wda.isRunning())) {
throw new ActionableError("WebDriverAgent is not running on device");
}
return wda;
}
```
资料来源：[src/ios.ts:82-97]()
#### WebDriverAgent Port Configuration
| Setting | Default Value | Purpose |
|---------|---------------|---------|
| WDA_PORT | 8100 | WebDriverAgent local port |
| IOS_TUNNEL_PORT | 9222 | iOS tunnel port |
### iOS Tunnel Requirements
When connecting to remote iOS devices, an **iOS tunnel** must be established. The tunnel allows the MCP server to communicate with devices over a network connection.
```typescript
private async assertTunnelRunning(): Promise {
if (await this.isTunnelRequired()) {
if (!(await this.isTunnelRunning())) {
throw new ActionableError("iOS tunnel is not running");
}
}
}
```
资料来源：[src/ios.ts:68-74]()
#### Tunnel Setup Requirements
1. **Port forwarding must be active** - The tunnel forwards WDA traffic to the local MCP server
2. **Firewall configuration** - Port 9222 must be accessible for tunnel connections
3. **Network connectivity** - Both server and device must have network access
### iOS Simulator Requirements
For iOS simulators, the system uses `simctl` commands through the Xcode toolchain:
```typescript
this.simctl("install", this.simulatorUuid, installPath);
```
资料来源：[src/iphone-simulator.ts:89]()
**Required tools for simulators:**
- Xcode Command Line Tools
- `simctl` utility
- Bootable simulator instances
### App Installation on iOS
The iOS manager handles `.zip` and `.app` bundle installations:
```typescript
if (extname(path).toLowerCase() === ".zip") {
this.validateZipPaths(path);
// Extract and install .app bundle
}
```
资料来源：[src/iphone-simulator.ts:58-65]()
Supported formats: `.zip`, `.app`
## Android-Specific Prerequisites
### Android Debug Bridge (ADB)
Android devices communicate through **ADB (Android Debug Bridge)**. The `MobileDevice` class executes ADB commands for device interaction:
```typescript
private runCommand(args: string[]): string {
const result = execFileSync("adb", ["-s", this.deviceId, ...args]);
return result.toString();
}
```
资料来源：[src/mobile-device.ts:17-20]()
#### Common ADB Operations
| Command | Purpose |
|---------|---------|
| `adb shell` | Execute shell commands on device |
| `adb install` | Install APK packages |
| `adb uninstall` | Remove applications |
| `adb screencap` | Capture screen screenshots |
| `adb input` | Send touch/keyboard input |
### Android Device Requirements
1. **USB Debugging enabled** - Required for ADB communication
2. **Device authorization** - Device must approve computer for debugging
3. **Proper USB drivers** - Especially on Windows systems
### Android UI Automation Commands
The Android implementation uses `uiautomator2` commands through ADB shell:
```typescript
public async getElementsOnScreen(): Promise {
const response = JSON.parse(this.runCommand(["dump", "ui"])) as DumpUIResponse;
return response.data.elements.map(element => ({
type: element.type,
label: element.label,
text: element.text,
// ... other properties
}));
}
```
资料来源：[src/mobile-device.ts:52-61]()
### Supported Android Input Operations
| Operation | ADB Command |
|-----------|-------------|
| Tap | `input tap x,y` |
| Swipe | `input swipe x1 y1 x2 y2` |
| Text input | `input text ` |
| Button press | `input keyevent ` |
| Long press | Custom implementation with duration |
## Architecture Overview
```mermaid
graph TB
subgraph "MCP Client"
A["AI Agent / IDE"]
end
subgraph "Mobile MCP Server"
B["server.ts
MCP Protocol Handler"]
C["Robot Interface
Abstract Layer"]
end
subgraph "Device Abstraction Layer"
D["IosRobot
iOS Implementation"]
E["AndroidRobot
Android Implementation"]
F["IosSimulatorRobot
Simulator Implementation"]
end
subgraph "Device Communication"
G["mobilecli"]
H["WebDriverAgent
iOS Real Devices"]
I["ADB
Android Devices"]
J["simctl
iOS Simulators"]
end
A --> B
B --> C
C --> D
C --> E
C --> F
D --> G
D --> H
E --> G
E --> I
F --> G
F --> J
```
## Prerequisites Checklist
Before running Mobile MCP, verify the following:
### Environment Checklist
- [ ] Node.js >= 18 installed
- [ ] `mobilecli` package accessible
- [ ] Network connectivity for remote devices
### iOS Device Checklist (Real Devices)
- [ ] WebDriverAgent installed on device
- [ ] iOS tunnel established (for remote access)
- [ ] Port forwarding active (port 8100)
- [ ] Device connected via USB or network
### iOS Simulator Checklist
- [ ] Xcode installed
- [ ] Simulator booted and available
- [ ] `simctl` command accessible
### Android Device Checklist
- [ ] ADB installed and in PATH
- [ ] USB debugging enabled on device
- [ ] Device authorized for debugging
- [ ] Device connected (USB or network)
## Troubleshooting Prerequisites Issues
### mobilecli Not Found
```
Error: mobilecli is not available or not working properly
```
**Solution:** Install mobilecli globally:
```bash
npm install -g mobilecli
```
### iOS Tunnel Not Running
```
Error: iOS tunnel is not running
```
**Solution:** Establish tunnel using `go-ios`:
```bash
ios tunnel start
```
### WebDriverAgent Not Running
```
Error: WebDriverAgent is not running on device
```
**Solution:**
1. Ensure WDA is installed on the device
2. Verify port forwarding: `iproxy 8100 8100`
3. Restart WebDriverAgent if needed
### Android Device Not Detected
```
Error: No Android devices found
```
**Solution:**
1. Verify ADB is running: `adb devices`
2. Enable USB debugging on device
3. Reconnect device or restart ADB: `adb kill-server && adb start-server`
## Related Documentation
- [Installation Guide](https://github.com/mobile-next/mobile-mcp/wiki)
- [iOS Setup](https://github.com/mobile-next/mobile-mcp/wiki/iOS-Setup)
- [Android Setup](https://github.com/mobile-next/mobile-mcp/wiki/Android-Setup)
- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki/Troubleshooting)
---
## System Architecture
### 相关页面
相关主题：[Device Abstraction Layer](#device-abstraction), [iOS Implementation](#ios-implementation)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)
- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)
- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
# System Architecture
## Overview
Mobile MCP is a Model Context Protocol (MCP) server that enables AI agents to interact with mobile devices (iOS and Android) through a standardized interface. The system acts as a bridge between LLM-powered agents and mobile device automation, supporting physical devices, simulators, and emulators.
资料来源：[README.md:1-50]()
## High-Level Architecture
The architecture follows a layered design pattern with clear separation of concerns:
```mermaid
graph TD
subgraph "Client Layer"
A["MCP Client
(Cursor, Claude, etc.)"]
end
subgraph "MCP Server Layer"
B["server.ts
(MCP Protocol Handler)"]
C["Tool Definitions"]
D["Device Manager"]
end
subgraph "Abstraction Layer"
E["Robot Interface
(robot.ts)"]
end
subgraph "Device Implementation Layer"
F["IosRobot
(ios.ts)"]
G["AndroidRobot
(android.ts)"]
H["MobileDevice
(mobile-device.ts)"]
end
subgraph "External Dependencies"
I["mobilecli"]
J["WebDriverAgent"]
K["ADB"]
end
A --> B
B --> C
B --> D
D --> E
E --> F
E --> G
E --> H
F --> J
G --> K
H --> I
```
## Core Components
### 1. MCP Server (`server.ts`)
The main entry point that implements the MCP protocol. It handles:
- Tool registration and discovery
- Device listing and selection
- Request routing to appropriate robot implementations
- Authentication handling (SSE mode)
Key responsibilities:
- Initializes the MCP SDK and registers all tools 资料来源：[src/server.ts:1-50]()
- Validates mobilecli availability at startup 资料来源：[src/server.ts:20-30]()
- Routes requests based on device type 资料来源：[src/server.ts:40-70]()
### 2. Robot Interface (`robot.ts`)
Defines the abstract interface that all device implementations must follow:
```typescript
interface Robot {
openUrl(url: string): Promise;
sendKeys(text: string): Promise;
pressButton(button: Button): Promise;
tap(x: number, y: number): Promise;
doubleTap(x: number, y: number): Promise;
longPress(x: number, y: number, duration: number): Promise;
swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;
getScreenshot(): Promise;
getElementsOnScreen(): Promise;
listApps(): Promise;
launchApp(packageName: string, locale?: string): Promise;
terminateApp(packageName: string): Promise;
installApp(path: string): Promise;
uninstallApp(bundleId: string): Promise;
setOrientation(orientation: Orientation): Promise;
getOrientation(): Promise;
}
```
资料来源：[src/robot.ts:1-100]()
### 3. Device Implementations
#### IosRobot (`ios.ts`)
Manages iOS device interactions through WebDriverAgent:
- Establishes tunnel connections for remote device access
- Manages WebDriverAgent port forwarding
- Provides iOS-specific automation commands
Key features:
- Port forwarding management (WDA_PORT = 8100, IOS_TUNNEL_PORT = 20021) 资料来源：[src/ios.ts:30-50]()
- WebDriverAgent lifecycle management 资料来源：[src/ios.ts:60-80]()
- Tunnel status validation 资料来源：[src/ios.ts:55-70]()
#### AndroidRobot (`android.ts`)
Manages Android device interactions through ADB:
- Direct ADB command execution
- Device discovery and listing
- APK installation and management
#### MobileDevice (`mobile-device.ts`)
Uses mobilecli for unified device control:
- Works across both platforms through mobilecli abstraction
- UI element dumping and interaction
- Device orientation management
资料来源：[src/mobile-device.ts:1-80]()
## Device Selection Flow
```mermaid
graph TD
A["mobile_list_available_devices"] --> B["Check iOS Devices"]
B --> C["Check Android Devices"]
C --> D["Check iOS Simulators"]
D --> E["Return Combined List"]
F["getRobotFromDevice
(deviceId)"] --> G{"Is iOS Device?"}
G -->|Yes| H["Return IosRobot"]
G -->|No| I{"Is Android Device?"}
I -->|Yes| J["Return AndroidRobot"]
I -->|No| K{"Is iOS Simulator?"}
K -->|Yes| L["Check Agent Status"]
L -->|Install if needed| M["Return MobileDevice"]
K -->|No| N["Throw Error"]
```
资料来源：[src/server.ts:60-100]()
## Tool Architecture
All MCP tools follow a consistent pattern defined in `server.ts`:
| Category | Tool Name | Purpose |
|----------|-----------|---------|
| Device Info | `mobile_list_available_devices` | List all connected devices |
| Device Info | `mobile_get_screen_size` | Get device screen dimensions |
| Device Info | `mobile_get_orientation` | Get current screen orientation |
| Device Info | `mobile_set_orientation` | Set screen orientation |
| App Management | `mobile_list_apps` | List installed apps |
| App Management | `mobile_launch_app` | Launch an app |
| App Management | `mobile_terminate_app` | Stop an app |
| App Management | `mobile_install_app` | Install from file |
| App Management | `mobile_uninstall_app` | Uninstall app |
| Screen Interaction | `mobile_take_screenshot` | Capture screen |
| Screen Interaction | `mobile_click_on_screen_at_coordinates` | Tap at coordinates |
| Screen Interaction | `mobile_double_tap_on_screen` | Double tap |
| Screen Interaction | `mobile_long_press_on_screen_at_coordinates` | Long press |
| Screen Interaction | `mobile_swipe_on_screen` | Swipe gesture |
| Input | `mobile_type_keys` | Send text input |
## Communication Protocols
### Stdio Mode (Default)
The default communication mode uses standard input/output:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
### SSE Server Mode
Optional HTTP server mode for remote access:
```bash
npx @mobilenext/mobile-mcp@latest --listen 3000
```
Supports optional Bearer token authentication:
```bash
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
## WebDriverAgent Integration (iOS)
For iOS devices, the architecture leverages WebDriverAgent:
```mermaid
sequenceDiagram
participant MCP as MCP Server
participant IosRobot
participant WDA as WebDriverAgent
participant Tunnel
MCP->>IosRobot: tap(x, y)
IosRobot->>Tunnel: Ensure tunnel running
Tunnel-->>IosRobot: OK
IosRobot->>WDA: POST /wda/tap/0
WDA-->>IosRobot: Response
IosRobot-->>MCP: Success
```
资料来源：[src/webdriver-agent.ts:50-100]()
## Dependency Architecture
```mermaid
graph LR
A["@modelcontextprotocol/sdk"] --> B["MCP Server"]
C["mobilecli"] --> D["MobileDevice"]
E["express"] --> F["SSE Server"]
G["zod"] --> H["Schema Validation"]
```
### Key Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| `@modelcontextprotocol/sdk` | 1.26.0 | MCP protocol implementation |
| `mobilecli` | 0.3.70 (optional) | Cross-platform mobile control |
| `express` | 5.1.0 | HTTP server for SSE mode |
| `zod` | ^4.1.13 | Runtime type validation |
| `commander` | 14.0.0 | CLI argument parsing |
资料来源：[package.json:1-50]()
## Error Handling
The system uses `ActionableError` for user-friendly error messages:
```typescript
throw new ActionableError(
`Device "${deviceId}" not found. Use the mobile_list_available_devices tool to see available devices.`
);
```
资料来源：[src/server.ts:90-95]()
## Platform Detection Logic
```mermaid
graph TD
A["getRobotFromDevice"] --> B["Check IosManager"]
B --> C{"Found in iOS devices?"}
C -->|Yes| D["Return IosRobot"]
C -->|No| E["Check AndroidManager"]
E --> F{"Found in Android devices?"}
F -->|Yes| G["Return AndroidRobot"]
F -->|No| H["Check iOS Simulators"]
H --> I{"Found?"}
I -->|Yes| J["Return MobileDevice"]
I -->|No| K["Throw ActionableError"]
```
## Security Considerations
- URL scheme validation: Only `http://` and `https://` allowed by default 资料来源：[src/server.ts:150-160]()
- Optional unsafe URL access via `MOBILEMCP_ALLOW_UNSAFE_URLS=1`
- Bearer token authentication for SSE mode
- No arbitrary command execution on host system
## Extensibility
The Robot interface design allows for additional platform implementations:
1. Implement the `Robot` interface
2. Add device detection in `getRobotFromDevice()`
3. Register new tools in `server.ts`
```typescript
// Example: Adding a new platform
const newPlatformDevice = new NewPlatformRobot(deviceId);
return newPlatformRobot;
```
This modular architecture enables easy addition of new device types or automation backends without modifying existing implementations.
---
## Device Abstraction Layer
### 相关页面
相关主题：[System Architecture](#system-architecture), [iOS Implementation](#ios-implementation)
Relevant Source Files
以下源码文件用于生成本页说明：
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)
- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)
# Device Abstraction Layer
## Overview
The Device Abstraction Layer (DAL) is the core architectural component of mobile-mcp that provides a unified interface for interacting with mobile devices across different platforms. It abstracts platform-specific implementations (iOS and Android) behind a common Robot interface, enabling AI agents and automated workflows to control mobile devices without knowledge of the underlying platform details.
The DAL serves as the bridge between the Model Context Protocol (MCP) server and the physical mobile devices, handling device detection, robot instantiation, and operation delegation.
## Architecture
```mermaid
graph TD
A[MCP Server] --> B[Device Abstraction Layer]
B --> C[Robot Factory]
C --> D{IOS Device?}
C --> E{Android Device?}
C --> F{Simulator?}
D --> G[IosRobot]
E --> H[AndroidRobot]
F --> I[MobileDevice]
G --> J[mobilecli / iOS Device Kit]
H --> K[ADB / UI Automator]
I --> J
```
## Core Components
### Robot Interface
The Robot interface (`src/robot.ts`) defines the contract that all platform-specific implementations must follow. This ensures consistent behavior regardless of the target device.
**File:** `src/robot.ts:1-80`
| Method | Description | Parameters | Return Type |
|--------|-------------|------------|-------------|
| `openUrl` | Open a URL in the device browser | `url: string` | `Promise` |
| `sendKeys` | Send keyboard input to device | `text: string` | `Promise` |
| `pressButton` | Simulate physical button press | `button: Button` | `Promise` |
| `tap` | Tap at screen coordinates | `x: number, y: number` | `Promise` |
| `doubleTap` | Double-tap at coordinates | `x: number, y: number` | `Promise` |
| `longPress` | Long press at coordinates | `x: number, y: number, duration: number` | `Promise` |
| `getElementsOnScreen` | Get interactive UI elements | - | `Promise` |
| `setOrientation` | Change screen orientation | `orientation: Orientation` | `Promise` |
| `getOrientation` | Get current orientation | - | `Promise` |
### Platform Implementations
#### IosRobot
Handles iOS device interactions using WebDriverAgent or iOS Device Kit as the underlying protocol.
**File:** `src/ios.ts`
| Capability | Description |
|------------|-------------|
| Simulator Support | Full support for iOS simulators |
| Real Device Support | Uses iOS Device Kit for physical devices |
| WebDriverAgent | Legacy support via go-ios |
#### AndroidRobot
Manages Android device interactions through ADB (Android Debug Bridge) and UI Automator.
**File:** `src/android.ts`
| Capability | Description |
|------------|-------------|
| Emulator Support | Full support for Android emulators |
| Real Device Support | Direct ADB communication |
| Foldable Support | Multi-screen device handling (v0.0.23+) |
#### MobileDevice
Unified device class for modern simulator/emulator management. Used as the primary interface for iOS simulators.
**File:** `src/mobile-device.ts`
| Feature | Description |
|---------|-------------|
| Agent Status Check | Verifies device readiness |
| Agent Install | Automatically installs required agents |
| Platform Abstraction | Works across iOS and Android platforms |
## Device Detection Flow
```mermaid
sequenceDiagram
participant Client
participant Server
participant DAL as Device Abstraction Layer
participant IosMgr as IosManager
participant AndroidMgr as AndroidDeviceManager
participant mobilecli
Client->>Server: Tool Request (deviceId)
Server->>DAL: getRobotFromDevice(deviceId)
DAL->>IosMgr: listDevices()
DAL->>AndroidMgr: getConnectedDevices()
alt iOS Device Found
DAL->>DAL: Create IosRobot(deviceId)
else Android Device Found
DAL->>DAL: Create AndroidRobot(deviceId)
else Simulator Check
DAL->>mobilecli: getDevices(platform: "ios", type: "simulator")
alt Simulator Found
DAL->>DAL: Check agentVerifiedSimulators
DAL->>mobilecli: agentStatus(deviceId)
alt Agent Not Installed
DAL->>mobilecli: agentInstall(deviceId)
end
DAL->>DAL: Create MobileDevice(deviceId)
else Not Found
DAL-->>Client: Error: Device not found
end
end
DAL-->>Server: Robot Instance
Server-->>Client: Execute Tool
```
## Device Manager Classes
### IosManager
Manages iOS device discovery and listing.
**File:** `src/ios.ts`
```typescript
class IosManager {
listDevices(): IosDevice[];
}
```
### AndroidDeviceManager
Manages Android device discovery via ADB.
**File:** `src/android.ts`
```typescript
class AndroidDeviceManager {
getConnectedDevices(): AndroidDevice[];
}
```
## mobilecli Integration
The mobilecli tool (`src/mobilecli.ts`) is the underlying CLI that provides cross-platform device management. It is a required dependency for the Device Abstraction Layer to function.
**File:** `src/server.ts:8-16`
```typescript
const ensureMobilecliAvailable = (): void => {
try {
const version = mobilecli.getVersion();
if (version.startsWith("failed")) {
throw new Error("mobilecli version check failed");
}
} catch (error: any) {
throw new ActionableError(`mobilecli is not available or not working properly...`);
}
};
```
### Key mobilecli Functions
| Function | Purpose |
|----------|---------|
| `getVersion()` | Verify mobilecli installation |
| `getDevices()` | List available devices by platform and type |
| `agentStatus()` | Check if agent is installed on device |
| `agentInstall()` | Install required agent on device |
| `agentUninstall()` | Remove agent from device |
## Simulator Agent Management
For iOS simulators, the DAL implements an agent verification and auto-installation system.
**File:** `src/server.ts:45-58`
```typescript
if (!agentVerifiedSimulators.has(deviceId)) {
const agentStatus = mobilecli.agentStatus(deviceId);
if (agentStatus.status === "fail") {
mobilecli.agentInstall(deviceId);
}
agentVerifiedSimulators.add(deviceId);
}
```
This ensures that:
1. Each simulator is checked at most once per server session
2. Missing agents are automatically installed
3. The `agentVerifiedSimulators` Set prevents redundant installations
## Error Handling
The DAL provides actionable error messages when device operations fail.
| Error Condition | Response |
|-----------------|----------|
| mobilecli not available | Links to installation wiki |
| Device not found | Lists available devices tool |
| iOS Device Kit failure | Fallback mechanisms |
**File:** `src/server.ts:15-16`
```typescript
throw new ActionableError(`Device "${deviceId}" not found.
Use the mobile_list_available_devices tool to see available devices.`);
```
## Usage in MCP Tools
The Device Abstraction Layer is invoked by all device interaction tools defined in the MCP server:
**File:** `src/server.ts:63-90`
| Tool | Operation |
|------|-----------|
| `mobile_list_available_devices` | Lists all connected devices |
| `mobile_get_screen_size` | Delegates to active Robot |
| `mobile_take_screenshot` | Delegates to active Robot |
| `mobile_click_on_screen_at_coordinates` | Delegates to active Robot |
| `mobile_type_keys` | Delegates to active Robot |
| `mobile_press_button` | Delegates to active Robot |
## Configuration
The DAL requires mobilecli as an optional dependency:
**File:** `package.json:22-23`
```json
"optionalDependencies": {
"mobilecli": "0.3.70"
}
```
## Summary
The Device Abstraction Layer provides:
- **Unified Interface**: A single `Robot` interface for all platform operations
- **Platform Detection**: Automatic identification of iOS, Android, and simulator devices
- **Factory Pattern**: Dynamic robot instantiation based on device type
- **Agent Management**: Automatic verification and installation of required agents
- **Error Context**: Actionable error messages with documentation links
This architecture enables mobile-mcp to provide a consistent automation experience across the diverse mobile device ecosystem while maintaining platform-specific optimizations.
---
## MCP Tools Reference
### 相关页面
相关主题：[Device Management](#device-management), [App Management](#app-management), [Screen Interaction and Input](#screen-interaction)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)
- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
# MCP Tools Reference
## Overview
The Mobile MCP server exposes a comprehensive set of tools that enable AI assistants to interact with mobile devices (iOS and Android) through the Model Context Protocol. These tools provide capabilities for device management, screen interaction, app lifecycle management, and UI automation. 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
The tools are implemented in TypeScript and follow a consistent pattern where each tool accepts a `device` parameter to specify the target device identifier. 资料来源：[src/server.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
## Architecture
### Tool Layer Hierarchy
```mermaid
graph TD
A[MCP Client
Claude, Cursor, Codex] --> B[Mobile MCP Server]
B --> C[Robot Interface]
C --> D[iOS Robot]
C --> E[Android Robot]
D --> F[WebDriverAgent]
D --> G[iPhone Simulator]
E --> H[Android ADB]
F --> I[Real iOS Device]
G --> J[iOS Simulator]
H --> K[Android Emulator]
H --> L[Android Device]
```
### Device Detection Flow
```mermaid
graph TD
A[getRobotFromDevice
deviceId: string] --> B{Is iOS Device?}
B -->|Yes| C[Return IosRobot]
B -->|No| D{Is Android Device?}
D -->|Yes| E[Return AndroidRobot]
D -->|No| F{Check iOS
Simulators?}
F -->|Found| G[Return IosRobot]
F -->|Not Found| H[Return Error]
```
The `getRobotFromDevice` function determines the appropriate robot implementation based on the device type by querying device managers and checking against known device identifiers. 资料来源：[src/server.ts:15-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
## Tool Categories
### Device Management Tools
#### mobile_list_available_devices
Lists all available mobile devices including simulators, emulators, and connected physical devices.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | No | Optional device filter |
**Response:** JSON array of device objects with `deviceId`, `name`, `platform`, and `status`.
#### mobile_get_screen_size
Retrieves the screen dimensions of the connected device in pixels.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
**Response:** `{ "width": number, "height": number }`
#### mobile_get_orientation
Returns the current screen orientation of the device.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
**Response:** `"portrait"` or `"landscape"` 资料来源：[src/mobile-device.ts:80-90](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
#### mobile_set_orientation
Changes the screen orientation of the device.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `orientation` | string | Yes | `"portrait"` or `"landscape"` |
```typescript
public async setOrientation(orientation: Orientation): Promise {
this.runCommand(["device", "orientation", "set", orientation]);
}
```
资料来源：[src/mobile-device.ts:75-79](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
---
### App Management Tools
#### mobile_list_apps
Lists all installed applications on the target device.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
**Response:** Array of installed app objects containing `bundleId`, `name`, and `version`.
#### mobile_launch_app
Launches an application by its package name (Android) or bundle identifier (iOS).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `app_id` | string | Yes | Bundle ID (iOS) or package name (Android) |
| `locale` | string | No | Optional locale to set before launching |
```typescript
launchApp(packageName: string, locale?: string): Promise;
```
#### mobile_terminate_app
Stops and terminates a running application. This is a no-op if the app is not running.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `app_id` | string | Yes | Bundle ID or package name |
#### mobile_install_app
Installs an application from a local file path. Supports `.apk`, `.ipa`, `.app`, and `.zip` formats.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `app_path` | string | Yes | Absolute path to the app file |
**Implementation Note:** For iOS simulators, ZIP files are automatically extracted and the `.app` bundle is identified for installation. 资料来源：[src/iphone-simulator.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)
#### mobile_uninstall_app
Removes an installed application from the device.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `app_id` | string | Yes | Bundle ID or package name |
---
### Screen Interaction Tools
#### mobile_take_screenshot
Captures the current screen and returns it as a PNG buffer for visual analysis.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
**Response:** Base64-encoded PNG image data.
#### mobile_save_screenshot
Captures and saves a screenshot to a specified file path.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `path` | string | Yes | Destination file path |
#### mobile_list_elements_on_screen
Retrieves all interactive UI elements visible on the screen with their properties.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
**Response:** Array of screen elements with the following properties:
| Property | Type | Description |
|----------|------|-------------|
| `type` | string | Element type (TextField, Button, Switch, etc.) |
| `label` | string | Accessibility label |
| `text` | string | Display text content |
| `name` | string | Element name |
| `value` | string | Current value |
| `identifier` | string | Unique element identifier |
| `rect` | object | Position and dimensions `{x, y, width, height}` |
| `focused` | boolean | Whether the element has focus |
**Implementation Note:** For iOS, this uses WebDriverAgent's page source API. For Android, it uses the accessibility tree via `dump ui` command. 资料来源：[src/webdriver-agent.ts:50-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
#### mobile_click_on_screen_at_coordinates
Performs a tap action at specific screen coordinates.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `x` | number | Yes | X coordinate |
| `y` | number | Yes | Y coordinate |
#### mobile_double_tap_on_screen
Performs a double-tap action at specific screen coordinates.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `x` | number | Yes | X coordinate |
| `y` | number | Yes | Y coordinate |
**Implementation:** On iOS WebDriverAgent, this uses pointer actions with pause between taps. On Android, it may execute two sequential taps. 资料来源：[src/webdriver-agent.ts:120-150](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
#### mobile_long_press_on_screen_at_coordinates
Performs a long press gesture at specified coordinates.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `x` | number | Yes | X coordinate |
| `y` | number | Yes | Y coordinate |
| `duration` | number | No | Press duration in milliseconds (default: 1000) |
#### mobile_swipe_on_screen
Performs a swipe gesture in a specified direction.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `direction` | string | Yes | `up`, `down`, `left`, or `right` |
| `start_x` | number | No | Starting X coordinate |
| `start_y` | number | No | Starting Y coordinate |
| `distance` | number | No | Swipe distance in pixels |
---
### Input & Navigation Tools
#### mobile_type_keys
Types text into the currently focused element with optional submit action.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `text` | string | Yes | Text to type |
| `submit` | boolean | No | Whether to press Enter after typing |
```typescript
public async sendKeys(text: string): Promise {
this.runCommand(["io", "text", text]);
}
```
资料来源：[src/mobile-device.ts:50-52](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
#### mobile_press_button
Simulates a physical button press on the device.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `button` | string | Yes | Button name (see supported buttons) |
**Supported Buttons:**
| Platform | Buttons |
|----------|---------|
| Android | `home`, `back`, `up`, `down`, `left`, `right`, `enter`, `delete` |
| iOS | `home`, `volumeUp`, `volumeDown` |
#### mobile_open_url
Opens a URL in the device's web browser or launches an app via custom URL scheme.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `url` | string | Yes | URL to open (https:// or custom scheme like `myapp://`) |
---
### Recording & Diagnostics Tools
#### mobile_start_recording
Starts screen recording on the device.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `output_path` | string | No | Output file path |
#### mobile_stop_recording
Stops the active screen recording and returns the output file information.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
**Response:** File path, size in MB, and duration in seconds.
#### mobile_list_crashes
Lists all crash reports available on the device.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
**Response:** JSON array of crash report objects with IDs and timestamps.
#### mobile_get_crash
Retrieves the full content of a specific crash report.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `device` | string | Yes | Target device identifier |
| `crash_id` | string | Yes | Crash report identifier |
---
## Robot Interface
The `Robot` interface defines the contract for all mobile device implementations:
```typescript
interface Robot {
// URL and Input
openUrl(url: string): Promise;
sendKeys(text: string): Promise;
pressButton(button: Button): Promise;
// Touch Gestures
tap(x: number, y: number): Promise;
doubleTap(x: number, y: number): Promise;
longPress(x: number, y: number, duration: number): Promise;
swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;
// Screen
getScreenshot(): Promise;
getElementsOnScreen(): Promise;
setOrientation(orientation: Orientation): Promise;
getOrientation(): Promise;
// App Management
listApps(): Promise;
launchApp(packageName: string, locale?: string): Promise;
terminateApp(packageName: string): Promise;
installApp(path: string): Promise;
uninstallApp(bundleId: string): Promise;
}
```
资料来源：[src/robot.ts:1-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
## Platform-Specific Implementations
### iOS Implementation
The iOS robot uses WebDriverAgent (WDA) for real devices and simctl for simulators:
```mermaid
graph TD
A[IosRobot] --> B{Device Type?}
B -->|Real Device| C[WebDriverAgent]
C --> D[WDA REST API]
D --> E[WDA Port Forwarding]
E --> F[iOS Device]
B -->|Simulator| G[iPhone Simulator]
G --> H[simctl CLI]
H --> I[Xcode Simulator]
```
**Port Requirements for Real iOS Devices:**
| Service | Port |
|---------|------|
| iOS Tunnel | 28000 |
| WDA Forward | 8100 |
The tunnel must be running and port forwarding established before WDA operations can proceed. 资料来源：[src/ios.ts:30-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
### Android Implementation
The Android robot uses ADB (Android Debug Bridge) for all device interactions:
```mermaid
graph TD
A[AndroidRobot] --> B[ADB Commands]
B --> C[UI Interaction: tap, swipe, text input]
B --> D[App Management: install, uninstall, launch]
B --> E[Device Info: orientation, screen size]
B --> F[Accessibility: dump ui tree]
```
**Android Element Discovery:**
The `dump ui` command returns a JSON response containing the accessibility tree:
```typescript
public async getElementsOnScreen(): Promise {
const response = JSON.parse(this.runCommand(["dump", "ui"])) as DumpUIResponse;
return response.data.elements.map(element => ({
type: element.type,
label: element.label,
text: element.text,
name: element.name,
value: element.value,
identifier: element.identifier,
rect: element.rect,
focused: element.focused,
}));
}
```
资料来源：[src/mobile-device.ts:55-70](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
## Tool Configuration
### Standard Configuration
Most MCP clients use the following standard configuration:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
### SSE Server Mode
For network-based connections, enable SSE mode with optional authentication:
```bash
# Basic SSE server
npx @mobilenext/mobile-mcp@latest --listen 3000
# With authentication
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
| Parameter | Description |
|-----------|-------------|
| `--listen` | Port to bind the SSE server |
| `MOBILEMCP_AUTH` | Bearer token for authorization |
---
## Error Handling
All tools validate device availability and return structured errors. Common error scenarios:
| Error | Cause | Resolution |
|-------|-------|------------|
| `Device not found` | Invalid device identifier | Use `mobile_list_available_devices` |
| `iOS tunnel not running` | Missing port forwarding | See [wiki](https://github.com/mobile-next/mobile-mcp/wiki/) |
| `WDA not running` | WebDriverAgent crashed | Restart WDA on device |
| `App not installed` | Invalid bundle ID | Verify with `mobile_list_apps` |
The `ActionableError` class provides user-friendly messages with links to troubleshooting documentation. 资料来源：[src/server.ts:20-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
---
## Quick Reference
### Essential Tools for UI Automation
| Task | Primary Tool | Secondary Tool |
|------|--------------|----------------|
| View screen | `mobile_take_screenshot` | `mobile_list_elements_on_screen` |
| Tap element | `mobile_click_on_screen_at_coordinates` | - |
| Type text | `mobile_type_keys` | - |
| Scroll | `mobile_swipe_on_screen` | - |
| Navigate back | `mobile_press_button` (back) | - |
### Device-Specific Tools
| Capability | iOS | Android |
|------------|-----|---------|
| Real device | Yes | Yes |
| Simulator | Yes | No |
| Emulator | No | Yes |
| WebDriverAgent | Yes (real) | N/A |
| ADB | N/A | Yes |
---
## Device Management
### 相关页面
相关主题：[MCP Tools Reference](#mcp-tools-reference), [Device Abstraction Layer](#device-abstraction)
Relevant Source Files
以下源码文件用于生成本页说明：
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)
- [src/utils.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/utils.ts)
- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)
# Device Management
## Overview
Device Management in Mobile MCP provides a unified abstraction layer for controlling mobile devices across iOS and Android platforms. It enables AI agents to interact with physical devices, simulators, and emulators through a consistent set of tools and APIs, abstracting platform-specific implementation details.
资料来源：[src/server.ts:1-50]()
## Architecture
The Device Management system follows a layered architecture:
```mermaid
graph TD
A[MCP Server] --> B[Device Manager]
B --> C[iOS Manager]
B --> D[Android Manager]
B --> E[Mobile CLI]
C --> F[iOS Robot]
D --> G[Android Robot]
E --> H[Mobile Device]
F --> I[Physical Device / Simulator]
G --> J[Emulator / Physical Device]
H --> K[iOS Simulator]
```
### Core Components
| Component | File | Purpose |
|-----------|------|---------|
| `Robot` interface | `src/robot.ts` | Defines unified device interaction contract |
| `IosRobot` | Platform-specific | Handles iOS device communication |
| `AndroidRobot` | Platform-specific | Handles Android device communication |
| `MobileDevice` | Platform-specific | Handles iOS simulators via mobilecli |
| `IosManager` | Internal | iOS device discovery and management |
| `AndroidDeviceManager` | Internal | Android device discovery and management |
资料来源：[src/robot.ts:1-50]()
## Device Discovery
Device discovery is performed through the `getRobotFromDevice()` function, which identifies the device type and returns the appropriate robot implementation.
```mermaid
graph TD
A[Start] --> B{Check iOS Devices}
B -->|Found| C[Return IosRobot]
B -->|Not Found| D{Check Android Devices}
D -->|Found| E[Return AndroidRobot]
D -->|Not Found| F{Check Simulators via mobilecli}
F -->|Simulator Found| G[Verify Agent Status]
G -->|Status Failed| H[Install Agent]
G -->|Status OK| I[Return MobileDevice]
F -->|Not Found| J[Throw Error]
```
### Device Detection Flow
The detection sequence in `src/server.ts`:
1. **iOS Physical Devices**: Uses `IosManager.listDevices()` to enumerate iOS devices
2. **Android Physical Devices**: Uses `AndroidDeviceManager.getConnectedDevices()` to enumerate Android devices
3. **iOS Simulators**: Uses `mobilecli.getDevices()` with `platform: "ios"` and `type: "simulator"`
资料来源：[src/server.ts:50-100]()
## Device Types Supported
### Platform Matrix
| Platform | Physical Devices | Simulators/Emulators | Key Technologies |
|----------|------------------|---------------------|------------------|
| iOS | iPhone, iPad | iOS Simulator | WebDriverAgent, iOS Device Kit |
| Android | Samsung, Pixel, etc. | Android Emulator | ADB, UI Automator |
### Simulator Agent Verification
When connecting to iOS simulators, Mobile MCP performs agent verification:
```typescript
if (!agentVerifiedSimulators.has(deviceId)) {
const agentStatus = mobilecli.agentStatus(deviceId);
if (agentStatus.status === "fail") {
mobilecli.agentInstall(deviceId);
}
agentVerifiedSimulators.add(deviceId);
}
```
资料来源：[src/server.ts:75-85]()
## Robot Interface
The `Robot` interface in `src/robot.ts` defines all device interaction methods:
### Screen Operations
| Method | Purpose | Return Type |
|--------|---------|-------------|
| `getScreenshot()` | Capture screen as PNG | `Promise` |
| `getScreenSize()` | Get screen dimensions | `Promise<{width, height}>` |
| `getOrientation()` | Get current orientation | `Promise` |
| `setOrientation()` | Set portrait/landscape | `Promise` |
### Touch Interactions
| Method | Purpose | Parameters |
|--------|---------|------------|
| `tap(x, y)` | Single tap | x, y coordinates |
| `doubleTap(x, y)` | Double tap | x, y coordinates |
| `longPress(x, y, duration)` | Long press | x, y, duration (ms) |
| `swipeFromCoordinate(x, y, direction, distance?)` | Swipe gesture | x, y, direction, optional distance |
### App Management
| Method | Purpose | Parameters |
|--------|---------|------------|
| `listApps()` | List installed apps | None |
| `launchApp(packageName, locale?)` | Launch app | package name, optional locale |
| `terminateApp(packageName)` | Stop app | package name |
| `installApp(path)` | Install from file | file path (.apk, .ipa, .app, .zip) |
| `uninstallApp(bundleId)` | Uninstall app | bundle ID/package name |
### Navigation & Input
| Method | Purpose | Parameters |
|--------|---------|------------|
| `sendKeys(text)` | Type text | string |
| `pressButton(button)` | Press button | Button enum (HOME, BACK, etc.) |
| `openUrl(url)` | Open URL/browser | URL string |
资料来源：[src/robot.ts:50-120]()
## Available Tools
Mobile MCP exposes the following device management tools to MCP clients:
### Device Information
- `mobile_list_available_devices` - List all connected devices (physical and simulators)
- `mobile_get_screen_size` - Get screen dimensions in pixels
- `mobile_get_orientation` - Get current screen orientation
- `mobile_set_orientation` - Change screen orientation (portrait/landscape)
- `mobile_list_crashes` - List crash reports on device
- `mobile_get_crash` - Retrieve full crash report content
### Screen Interaction
- `mobile_take_screenshot` - Capture screenshot
- `mobile_save_screenshot` - Save screenshot to file
- `mobile_list_elements_on_screen` - Get UI elements with coordinates
- `mobile_click_on_screen_at_coordinates` - Click at x,y
- `mobile_double_tap_on_screen` - Double tap at x,y
- `mobile_long_press_on_screen_at_coordinates` - Long press at x,y
- `mobile_swipe_on_screen` - Swipe in direction
### Input & Navigation
- `mobile_type_keys` - Type text into focused elements
- `mobile_press_button` - Press device buttons
- `mobile_open_url` - Open URL in browser
### App Management
- `mobile_list_apps` - List installed apps
- `mobile_launch_app` - Launch app by package name
- `mobile_terminate_app` - Stop running app
- `mobile_install_app` - Install from file
- `mobile_uninstall_app` - Uninstall app
## Prerequisites
Device management requires the `mobilecli` tool to be available on the system. The server validates this on startup:
```typescript
const ensureMobilecliAvailable = (): void => {
try {
const version = mobilecli.getVersion();
if (version.startsWith("failed")) {
throw new Error("mobilecli version check failed");
}
} catch (error: any) {
throw new ActionableError(`mobilecli is not available...`);
}
};
```
资料来源：[src/server.ts:20-35]()
## Configuration
### MCP Server Configuration
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
### SSE Server Mode with Authentication
```bash
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
When `MOBILEMCP_AUTH` is set, all requests require the header:
```
Authorization: Bearer my-secret-token
```
资料来源：[package.json:1-30]()
## Error Handling
The device management system uses `ActionableError` to provide users with actionable error messages:
```typescript
throw new ActionableError(
`Device "${deviceId}" not found. Use the mobile_list_available_devices tool to see available devices.`
);
```
This pattern ensures users receive guidance on how to resolve issues, not just failure messages.
资料来源：[src/server.ts:95-100]()
## Dependencies
| Dependency | Version | Purpose |
|------------|---------|---------|
| `@modelcontextprotocol/sdk` | 1.26.0 | MCP protocol implementation |
| `mobilecli` | 0.3.70 (optional) | Cross-platform mobile CLI |
| `express` | 5.1.0 | SSE server transport |
| `zod` | ^4.1.13 | Schema validation |
资料来源：[package.json:25-50]()
## See Also
- [Prompt Examples](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)
- [Installation Guide](https://github.com/mobile-next/mobile-mcp/wiki)
- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki)
---
## App Management
### 相关页面
相关主题：[MCP Tools Reference](#mcp-tools-reference), [iOS Implementation](#ios-implementation)
Relevant Source Files
The following source files were used to generate this documentation:
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)
# App Management
App Management in Mobile MCP enables AI agents to interact with mobile applications on connected devices through a unified interface. This system provides capabilities for listing, launching, terminating, installing, and uninstalling applications across both iOS and Android platforms.
## Overview
The App Management feature abstracts platform-specific implementation details behind a consistent Robot interface. This allows AI agents to manage applications without understanding the underlying differences between iOS and Android platforms.
```mermaid
graph TD
A[MCP Client / AI Agent] --> B[Mobile MCP Server]
B --> C[Robot Interface]
C --> D[iOS Robot]
C --> E[Android Robot]
D --> F[WebDriverAgent / go-ios]
E --> G[ADB / Android Manager]
```
**资料来源：** [src/robot.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
## Available Tools
Mobile MCP exposes five primary tools for application management:
| Tool | Description | Platform |
|------|-------------|----------|
| `mobile_list_apps` | List all installed applications | iOS, Android |
| `mobile_launch_app` | Launch an app by package/bundle name | iOS, Android |
| `mobile_terminate_app` | Stop a running application | iOS, Android |
| `mobile_install_app` | Install app from file (.apk, .ipa, .app, .zip) | iOS, Android |
| `mobile_uninstall_app` | Uninstall app by bundle ID or package name | iOS, Android |
**资料来源：** [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)
## Robot Interface
The core App Management functionality is defined in the `Robot` interface. This interface declares abstract methods that platform-specific implementations must provide.
```typescript
interface Robot {
listApps(): Promise;
launchApp(packageName: string, locale?: string): Promise;
terminateApp(packageName: string): Promise;
installApp(path: string): Promise;
uninstallApp(bundleId: string): Promise;
openUrl(url: string): Promise;
}
```
**资料来源：** [src/robot.ts:40-75](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
### Method Specifications
#### listApps()
Returns all installed applications on the device.
```typescript
listApps(): Promise;
```
**Return Type:** `InstalledApp[]` - Array of objects containing package names (Android) or bundle identifiers (iOS).
#### launchApp()
Launches an application with optional locale specification.
```typescript
launchApp(packageName: string, locale?: string): Promise;
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `packageName` | `string` | The package name (Android) or bundle ID (iOS) of the app |
| `locale` | `string` (optional) | Locale to launch the app with (e.g., "en_US") |
**资料来源：** [src/robot.ts:47-49](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
#### terminateApp()
Terminates a running application. If the app is not running or doesn't exist, this operation is a no-op.
```typescript
terminateApp(packageName: string): Promise;
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `packageName` | `string` | The package name (Android) or bundle ID (iOS) |
#### installApp()
Installs an application from a local file path. Supports multiple formats across platforms.
```typescript
installApp(path: string): Promise;
```
**Supported Formats:**
| Platform | Formats |
|----------|---------|
| Android | `.apk`, `.zip` |
| iOS | `.ipa`, `.app`, `.zip` |
#### uninstallApp()
Uninstalls an application from the device.
```typescript
uninstallApp(bundleId: string): Promise;
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `bundleId` | `string` | The app's bundle identifier (iOS) or package name (Android) |
#### openUrl()
Opens a URL in the device's web browser.
```typescript
openUrl(url: string): Promise;
```
**Supported URL Schemes:**
| Type | Example |
|------|---------|
| HTTP/HTTPS | `https://example.com` |
| Custom Schemes | `myapp://action` |
**资料来源：** [src/robot.ts:59-63](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
## Architecture
### Device Selection Flow
When a tool requires device-specific implementation, the server determines the appropriate Robot based on the device type:
```mermaid
graph TD
A[Device ID Provided] --> B{Is iOS Device?}
B -->|Yes| C[Return IosRobot]
B -->|No| D{Is Android Device?}
D -->|Yes| E[Return AndroidRobot]
D -->|No| F{Is Simulator?}
F -->|Yes| G[Return MobileDevice]
F -->|No| H[Throw ActionableError]
```
**资料来源：** [src/server.ts:30-60](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
### iOS Implementation
The iOS implementation leverages `go-ios` (via `mobilecli`) for device communication. The `IosManager` handles device detection and the `WebDriverAgent` protocol manages application lifecycle.
Key components in iOS app management:
1. **WebDriverAgent (WDA)** - Apple's testing framework for iOS
2. **go-ios** - Command-line interface for iOS device control
3. **Tunnel Service** - Required for real device communication
**资料来源：** [src/ios.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
### Android Implementation
Android implementation uses the Android Debug Bridge (ADB) through the Android Manager:
1. **ADB** - Primary communication protocol with Android devices
2. **Android Manager** - Handles device enumeration and app operations
3. **Package Manager** - Manages app installation and uninstallation
## Tool Registration
App Management tools are registered in the server with descriptive schemas:
```typescript
tool(
"mobile_list_apps",
"List Apps",
"List all installed apps on the device",
{},
{ readOnlyHint: true },
async ({}) => { /* implementation */ }
);
```
**资料来源：** [src/server.ts:80-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
## Prerequisites
### iOS Requirements
- WebDriverAgent must be running on the device
- For real devices: iOS tunnel must be established
- go-ios must be installed and functional
**资料来源：** [src/ios.ts:35-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
### Android Requirements
- ADB must be enabled on the device
- Device must be connected and authorized
- USB debugging must be enabled
## Usage Examples
### List All Installed Apps
```json
{
"tool": "mobile_list_apps",
"arguments": {}
}
```
### Launch an App with Locale
```json
{
"tool": "mobile_launch_app",
"arguments": {
"packageName": "com.example.app",
"locale": "en_US"
}
}
```
### Install an App
```json
{
"tool": "mobile_install_app",
"arguments": {
"path": "/path/to/application.apk"
}
}
```
### Uninstall an App
```json
{
"tool": "mobile_uninstall_app",
"arguments": {
"bundleId": "com.example.app"
}
}
```
### Open URL in Browser
```json
{
"tool": "mobile_open_url",
"arguments": {
"url": "https://example.com"
}
}
```
## Error Handling
The system provides actionable error messages when operations fail. Common error scenarios include:
| Error Condition | Cause | Resolution |
|-----------------|-------|------------|
| Device not found | Invalid device ID or disconnected device | Check device connection |
| App not installed | Attempting to launch non-existent app | Install app first |
| Installation failed | Invalid file format or corrupted package | Verify file integrity |
| Permission denied | Insufficient device permissions | Grant required permissions |
**资料来源：** [src/server.ts:45-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
## Dependencies
App Management relies on the following package:
| Package | Version | Purpose |
|---------|---------|---------|
| `mobilecli` | 0.3.70 | Cross-platform mobile device CLI |
**资料来源：** [package.json:25-30](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)
---
## Screen Interaction and Input
### 相关页面
相关主题：[MCP Tools Reference](#mcp-tools-reference), [iOS Implementation](#ios-implementation)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)
- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
# Screen Interaction and Input
## Overview
The Screen Interaction and Input system in Mobile MCP provides a comprehensive abstraction layer for controlling mobile devices (iOS, Android, simulators, and emulators) through a unified Robot interface. This system enables AI agents to interact with mobile applications by simulating user input events, capturing screen content, and managing device orientation.
The architecture is designed to work with multiple device platforms while presenting a consistent API to MCP clients. The system leverages native accessibility trees for most interactions, falling back to screenshot-based coordinate operations when accessibility labels are unavailable. 资料来源：[src/robot.ts:1-30]()
## Architecture
### Core Components
The system consists of three primary device abstraction layers:
| Component | Platform | Protocol | File |
|-----------|----------|----------|------|
| `IosRobot` | iOS | WebDriverAgent (WDA) | [src/webdriver-agent.ts:1-50]() |
| `AndroidRobot` | Android | mobilecli | [src/mobile-device.ts:1-30]() |
| `Robot` (interface) | All | Abstract | [src/robot.ts:1-50]() |
### Robot Interface Contract
The `Robot` interface defines the contract that all platform-specific implementations must fulfill:
```typescript
interface Robot {
openUrl(url: string): Promise;
sendKeys(text: string): Promise;
pressButton(button: Button): Promise;
tap(x: number, y: number): Promise;
doubleTap(x: number, y: number): Promise;
longPress(x: number, y: number, duration: number): Promise;
getElementsOnScreen(): Promise;
setOrientation(orientation: Orientation): Promise;
getOrientation(): Promise;
swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;
getScreenshot(): Promise;
listApps(): Promise;
launchApp(packageName: string, locale?: string): Promise;
terminateApp(packageName: string): Promise;
installApp(path: string): Promise;
uninstallApp(bundleId: string): Promise;
}
```
资料来源：[src/robot.ts:30-100]()
### Device Selection Flow
The server determines which Robot implementation to use based on the device identifier:
```mermaid
graph TD
A[MCP Request with device ID] --> B{Device Type Check}
B -->|iOS Device| C[IosRobot]
B -->|Android Device| D[AndroidRobot]
B -->|Simulator| E[IosRobot]
C --> F[WebDriverAgent Connection]
D --> G[mobilecli Commands]
E --> F
```
资料来源：[src/server.ts:50-80]()
## Touch Interactions
### Tap Operations
#### Single Tap
Single tap is implemented using pointer actions sent through the WebDriverAgent protocol for iOS:
```typescript
public async tap(x: number, y: number) {
await this.withinSession(async sessionUrl => {
const url = `${sessionUrl}/actions`;
await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
actions: [{
type: "pointer",
id: "finger1",
parameters: { pointerType: "touch" },
actions: [
{ type: "pointerMove", duration: 0, x, y },
{ type: "pointerDown", button: 0 },
{ type: "pause", duration: 100 },
{ type: "pointerUp", button: 0 }
]
}]
}),
});
});
}
```
资料来源：[src/webdriver-agent.ts:180-210]()
For Android, the tap operation uses the mobilecli command:
```typescript
public async tap(x: number, y: number): Promise {
this.runCommand(["io", "tap", `${x},${y}`]);
}
```
资料来源：[src/mobile-device.ts:50-52]()
#### Double Tap
Double tap is implemented by executing two consecutive tap operations:
```typescript
public async doubleTap(x: number, y: number): Promise {
await this.tap(x, y);
await this.tap(x, y);
}
```
资料来源：[src/mobile-device.ts:56-60]()
In iOS WebDriverAgent, the double tap uses the W3C Actions API with multiple pointer sequences.
#### Long Press
Long press requires specifying the duration in milliseconds:
```typescript
public async longPress(x: number, y: number, duration: number): Promise {
this.runCommand(["io", "longpress", `${x},${y}`, "--duration", `${duration}`]);
}
```
资料来源：[src/mobile-device.ts:62-64]()
The iOS implementation uses the Actions API with extended pointerDown duration:
```typescript
{ type: "pointerDown", button: 0 },
{ type: "pause", duration: duration },
{ type: "pointerUp", button: 0 }
```
### Swipe Gestures
Swipe gestures calculate coordinates based on screen dimensions, using 60% of the screen width or height as the swipe distance:
```typescript
const verticalDistance = Math.floor(screenSize.height * 0.6);
const horizontalDistance = Math.floor(screenSize.width * 0.6);
const centerX = Math.floor(screenSize.width / 2);
const centerY = Math.floor(screenSize.height / 2);
```
资料来源：[src/webdriver-agent.ts:130-135]()
The swipe direction determines the start and end coordinates:
| Direction | X Movement | Y Movement |
|-----------|------------|------------|
| up | centerX | centerY ± verticalDistance/2 |
| down | centerX | centerY ± verticalDistance/2 |
| left | centerX ± horizontalDistance/2 | centerY |
| right | centerX ± horizontalDistance/2 | centerY |
## Text Input
### Keyboard Input
Text input is handled through different mechanisms per platform:
**iOS (via WebDriverAgent):**
```typescript
public async sendKeys(text: string): Promise {
await this.withinSession(async sessionUrl => {
await fetch(`${sessionUrl}/wda/keys`, {
method: "POST",
body: JSON.stringify({ value: text.split("") }),
});
});
}
```
**Android (via mobilecli):**
```typescript
public async typeText(text: string): Promise {
this.runCommand(["io", "text", text]);
}
```
资料来源：[src/mobile-device.ts:42-44]()
### Button Presses
Physical device buttons are mapped to platform-specific commands:
| Button | iOS Action | Android Command |
|--------|------------|-----------------|
| HOME | `wda/pressButton` | `io button home` |
| BACK | N/A | `io button back` |
| POWER | N/A | `io button power` |
| ENTER | sendKeys "\n" | `io button enter` |
| VOLUME_UP | `wda/pressButton` | `io button volume_up` |
| VOLUME_DOWN | `wda/pressButton" | `io button volume_down` |
资料来源：[src/webdriver-agent.ts:150-175]()
## Screen Capture
### Screenshot Retrieval
Screenshots are retrieved as PNG buffers through platform-specific protocols:
**iOS WebDriverAgent:**
```typescript
public async getScreenshot(): Promise {
const url = `http://${this.host}:${this.port}/screenshot`;
const response = await fetch(url);
const json = await response.json();
return Buffer.from(json.value, "base64");
}
```
资料来源：[src/webdriver-agent.ts:100-106]()
**Android (via mobilecli):** Screenshots are captured using the platform's native screenshot mechanism through the `dump` command.
## UI Element Discovery
### Element Filtering
The system filters accessibility elements to return only actionable UI components:
```typescript
const acceptedTypes = [
"TextField",
"Button",
"Switch",
"Icon",
"SearchField",
"StaticText",
"Image"
];
```
资料来源：[src/webdriver-agent.ts:30-32]()
Element visibility is determined by checking both the `isVisible` flag and bounds:
```typescript
if (acceptedTypes.includes(source.type)) {
if (source.isVisible === "1" && this.isVisible(source.rect)) {
if (source.label !== null || source.name !== null || source.rawIdentifier !== null) {
output.push({ /* element data */ });
}
}
}
```
### Element Data Structure
Each screen element contains:
| Property | Type | Description |
|----------|------|-------------|
| type | string | Element type (Button, TextField, etc.) |
| label | string | Accessibility label |
| name | string | Element name |
| value | string | Current value (for text fields) |
| identifier | string | Platform-specific identifier |
| rect | {x, y, width, height} | Bounding rectangle |
| focused | boolean | Focus state |
资料来源：[src/mobile-device.ts:66-76]()
## Orientation Management
Device orientation can be queried and changed:
```typescript
public async setOrientation(orientation: Orientation): Promise {
this.runCommand(["device", "orientation", "set", orientation]);
}
public async getOrientation(): Promise {
const response = JSON.parse(this.runCommand(["device", "orientation", "get"])) as OrientationResponse;
return response.data.orientation;
}
```
资料来源：[src/mobile-device.ts:78-85]()
Supported orientations: `"portrait"` | `"landscape"`
## Connection Prerequisites
### iOS Requirements
iOS devices require several connection layers to be operational:
```mermaid
graph LR
A[MCP Server] --> B[iOS Tunnel]
B --> C[WDA Port Forward]
C --> D[WebDriverAgent]
D --> E[iOS Device]
F[Check: Tunnel Running] --> B
G[Check: WDA Forward Running] --> C
H[Check: WDA isRunning] --> D
```
资料来源：[src/ios.ts:30-60]()
The system verifies:
1. **Tunnel Running** - Required for remote iOS devices
2. **WDA Port Forward** - TCP port forwarding to WebDriverAgent
3. **WebDriverAgent Status** - Actual running state of WDA on device
```typescript
private async assertTunnelRunning(): Promise {
if (await this.isTunnelRequired()) {
if (!(await this.isTunnelRunning())) {
throw new ActionableError("iOS tunnel is not running...");
}
}
}
```
## MCP Tools Interface
The server exposes the following screen interaction tools:
| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| `mobile_take_screenshot` | Capture current screen | device |
| `mobile_list_elements_on_screen` | Get UI elements | device |
| `mobile_click_on_screen_at_coordinates` | Tap at coordinates | device, x, y |
| `mobile_double_tap_on_screen` | Double tap | device, x, y |
| `mobile_long_press_on_screen_at_coordinates` | Long press | device, x, y, duration |
| `mobile_swipe_on_screen` | Swipe gesture | device, direction |
| `mobile_type_keys` | Text input | device, text, submit |
| `mobile_get_orientation` | Query orientation | device |
| `mobile_set_orientation` | Set orientation | device, orientation |
## Usage Examples
### Basic Screen Interaction Workflow
```typescript
// 1. List available devices
const devices = await listAvailableDevices();
// 2. Get screen elements
const elements = await getElementsOnScreen(deviceId);
// 3. Tap on a button by coordinates
await tap(deviceId, 150, 300);
// 4. Type text into a field
await typeKeys(deviceId, "Hello World", false);
// 5. Swipe up to scroll
await swipe(deviceId, "up");
// 6. Take screenshot to verify
const screenshot = await getScreenshot(deviceId);
```
### Complete User Journey Automation
```typescript
// Open app and perform multi-step interaction
await launchApp(deviceId, "com.example.app");
await swipe(deviceId, "up");
const elements = await getElementsOnScreen(deviceId);
const loginButton = elements.find(e => e.name === "Login");
await tap(deviceId, loginButton.rect.x + 10, loginButton.rect.y + 10);
await typeKeys(deviceId, "user@example.com", false);
await pressButton(deviceId, "ENTER");
```
## Error Handling
The system provides actionable error messages with troubleshooting links:
```typescript
throw new ActionableError(
`mobilecli is not available or not working properly.
Please review the documentation at
https://github.com/mobile-next/mobile-mcp/wiki`
);
```
资料来源：[src/server.ts:20-25]()
Common error scenarios:
| Error Condition | Cause | Resolution |
|----------------|-------|------------|
| "iOS tunnel is not running" | Remote device connection issue | Start tunnel per wiki instructions |
| "Port forwarding not running" | WDA port not forwarded | Configure port forwarding |
| "WebDriverAgent not running" | WDA crashed on device | Restart WDA on iOS device |
## Performance Considerations
- **Element queries** use native accessibility trees for speed
- **Screenshots** are transferred as base64-encoded PNG
- **Gestures** are calculated as percentages of screen dimensions
- **Timeouts** for recording operations default to 5 minutes (300 seconds)
---
## iOS Implementation
### 相关页面
相关主题：[Device Abstraction Layer](#device-abstraction), [Screen Interaction and Input](#screen-interaction)
相关源码文件
以下源码文件用于生成本页说明：
- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)
- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)
- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)
- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)
- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)
# iOS Implementation
## Overview
The iOS Implementation module provides comprehensive automation capabilities for iOS devices, including physical devices, simulators, and emulators. This module serves as a bridge between the Mobile MCP server and iOS testing infrastructure, enabling AI agents to interact with iOS applications through accessibility trees and coordinate-based input.
**Purpose:** The iOS Implementation enables native app automation for iOS testing, scripted flows, and multi-step user journeys driven by LLMs.
**Scope:** The module handles device detection, connection management, WebDriverAgent communication, tunnel port forwarding, and command execution via the go-ios library.
资料来源：[src/ios.ts:1-50]()
## Architecture
The iOS implementation follows a layered architecture that separates device management, robot control, and protocol communication.
```mermaid
graph TD
A[MCP Server] --> B[IosManager]
A --> C[IosRobot]
B --> D[go-ios / mobilecli]
C --> E[WebDriverAgent]
C --> F[iOS Device Kit]
E --> G[Physical iOS Device]
F --> G
D --> H[iOS Simulator]
I[iPhone Simulator] --> H
```
### Core Components
| Component | File | Responsibility |
|-----------|------|-----------------|
| IosManager | src/server.ts | Device discovery and listing |
| IosRobot | src/server.ts | Device interaction via Robot interface |
| IosDeviceConnection | src/ios.ts | Connection and tunnel management |
| WebDriverAgent | src/webdriver-agent.ts | UI automation protocol |
| iPhone Simulator | src/iphone-simulator.ts | Simulator-specific operations |
资料来源：[src/server.ts:30-80]()
## Device Detection
The system uses a multi-step detection process to identify iOS device types and establish appropriate communication channels.
### Device Type Resolution
```mermaid
graph TD
A[Device ID] --> B{IosManager listDevices?}
B -->|Found| C[IosRobot]
B -->|Not Found| D{AndroidDeviceManager?}
D -->|Found| E[AndroidRobot]
D -->|Not Found| F{mobilecli getDevices?}
F -->|Simulator Found| G{MobileDevice}
F -->|Not Found| H[Error: Device not found]
```
The `getRobotFromDevice` function performs the following checks in order:
1. **iOS Physical Devices:** Queries IosManager for connected iOS devices 资料来源：[src/server.ts:45-50]()
2. **Android Devices:** Checks AndroidDeviceManager for matching device ID 资料来源：[src/server.ts:52-56]()
3. **iOS Simulators:** Uses mobilecli with platform filter for simulators 资料来源：[src/server.ts:58-75]()
### Simulator Agent Verification
For iOS simulators, the system automatically verifies and installs the agent if needed:
```typescript
if (!agentVerifiedSimulators.has(deviceId)) {
const agentStatus = mobilecli.agentStatus(deviceId);
if (agentStatus.status === "fail") {
mobilecli.agentInstall(deviceId);
}
agentVerifiedSimulators.add(deviceId);
}
```
资料来源：[src/server.ts:65-71]()
## Connection Management
### Port-Based Connection State
The iOS implementation uses port checking to verify connection states:
```mermaid
graph LR
A[Device] -->|USB Tunnel| B[localhost:PORT]
B --> C{WDA Port Check}
C -->|Listening| D[WebDriverAgent Ready]
C -->|Not Listening| E[Error: Port forwarding not running]
```
#### Tunnel Requirements
The `isTunnelRequired` method determines when tunnel port forwarding is necessary based on connection type. When a tunnel is required but not running, the system throws an `ActionableError`:
```typescript
private async assertTunnelRunning(): Promise {
if (await this.isTunnelRequired()) {
if (!(await this.isTunnelRunning())) {
throw new ActionableError("iOS tunnel is not running, please see https://github.com/mobile-next/mobile-mcp/wiki/");
}
}
}
```
资料来源：[src/ios.ts:45-50]()
#### WebDriverAgent Port Forwarding
Connection to WebDriverAgent requires both tunnel and port forwarding verification:
```typescript
private async wda(): Promise {
await this.assertTunnelRunning();
if (!(await this.isWdaForwardRunning())) {
throw new ActionableError("Port forwarding to WebDriverAgent is not running (tunnel okay), please see https://github.com/mobile-next/mobile-mcp/wiki/");
}
const wda = new WebDriverAgent("localhost", WDA_PORT);
if (!(await wda.isRunning())) {
throw new ActionableError("WebDriverAgent is not running on device (tunnel okay, port forwarding okay), please see https://github.com/mobile-next/mobile-mcp/wiki/");
}
return wda;
}
```
资料来源：[src/ios.ts:55-70]()
## Robot Interface Implementation
The IosRobot class implements the Robot interface, providing unified access to iOS device capabilities.
### Supported Operations
| Category | Operations |
|----------|------------|
| **Screen** | getScreenshot, getScreenSize, getOrientation, setOrientation |
| **Touch** | tap, doubleTap, longPress, swipeFromCoordinate |
| **Input** | sendKeys, pressButton |
| **Navigation** | home, back, openUrl |
| **Apps** | listApps, launchApp, terminateApp, installApp, uninstallApp |
| **Elements** | getElementsOnScreen |
资料来源：[src/robot.ts:1-80]()
### iOS-Specific Considerations
#### Accessibility Tree
The implementation uses native accessibility trees for element detection rather than computer vision, making it LLM-friendly and fast.
> **Note:** The `getElementsOnScreen` method works only on native apps and will not function within webviews.
资料来源：[src/robot.ts:40-45]()
#### Long Press Duration
The long press operation accepts a custom duration parameter:
```typescript
longPress(x: number, y: number, duration: number): Promise;
```
| Parameter | Type | Description |
|-----------|------|-------------|
| x | number | X coordinate on screen |
| y | number | Y coordinate on screen |
| duration | number | Duration in milliseconds |
资料来源：[src/robot.ts:35-38]()
## WebDriverAgent Integration
The WebDriverAgent (WDA) serves as the primary automation protocol for iOS physical devices.
### Connection Flow
```mermaid
sequenceDiagram
participant MCP as MCP Server
participant Ios as IosDeviceConnection
participant WDA as WebDriverAgent
participant Device as iOS Device
MCP->>Ios: wda()
Ios->>Ios: assertTunnelRunning()
Ios->>Ios: isWdaForwardRunning()
Ios->>WDA: new WebDriverAgent(localhost, PORT)
WDA->>Device: isRunning()
Device-->>WDA: status
WDA-->>Ios: WebDriverAgent instance
Ios-->>MCP: Ready for commands
```
### Port Configuration
| Port | Purpose | Configuration |
|------|---------|---------------|
| WDA_PORT | WebDriverAgent communication | localhost:PORT |
| IOS_TUNNEL_PORT | USB tunnel forwarding | localhost:PORT |
资料来源：[src/webdriver-agent.ts:1-30]()
## iOS Simulator Support
The iPhone Simulator module provides specialized handling for iOS Simulator instances.
### Simulator Detection
Simulators are detected through mobilecli with the following parameters:
```typescript
const response = mobilecli.getDevices({
platform: "ios",
type: "simulator",
includeOffline: false,
});
```
资料来源：[src/server.ts:58-62]()
### Simulator vs Physical Device
| Aspect | Simulator | Physical Device |
|--------|-----------|------------------|
| **Connection** | Direct via mobilecli | USB tunnel + WDA |
| **Agent** | Auto-installed on demand | Manual setup required |
| **Port Forwarding** | Not required | Required (WDA_PORT) |
| **WebDriverAgent** | Optional auto-start | Required |
资料来源：[src/iphone-simulator.ts:1-40]()
## go-ios Integration
The implementation uses the go-ios binary for low-level iOS device communication.
### Command Execution
```typescript
private async ios(...args: string[]): Promise {
return execFileSync(getGoIosPath(), ["--udid", this.deviceId, ...args], {}).toString();
}
```
资料来源：[src/ios.ts:75-77]()
### Utility Functions
The system checks for mobilecli availability on startup:
```typescript
const ensureMobilecliAvailable = (): void => {
try {
const version = mobilecli.getVersion();
if (version.startsWith("failed")) {
throw new Error("mobilecli version check failed");
}
} catch (error: any) {
throw new ActionableError(`mobilecli is not available or not working properly. Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki for installation instructions`);
}
};
```
资料来源：[src/server.ts:22-32]()
## Error Handling
### Actionable Errors
The system throws `ActionableError` with user-friendly messages and documentation links:
| Error Scenario | Message | Resolution Link |
|----------------|---------|-----------------|
| mobilecli unavailable | Installation instructions | [Wiki Installation](https://github.com/mobile-next/mobile-mcp/wiki) |
| Tunnel not running | Setup guide | [Wiki Tunnel Setup](https://github.com/mobile-next/mobile-mcp/wiki) |
| Port forwarding failed | Troubleshooting | [Wiki Debugging](https://github.com/mobile-next/mobile-mcp/wiki) |
| WDA not running | Configuration guide | [Wiki WDA Setup](https://github.com/mobile-next/mobile-mcp/wiki) |
| Device not found | Device list | mobile_list_available_devices tool |
资料来源：[src/ios.ts:48-70]()
## Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| MOBILEMCP_AUTH | Bearer token for SSE authorization | None |
### Port Constants
The system uses standard port configurations for iOS tunnel and WDA communication. Refer to the source code for current port values.
## Platform Support Matrix
| Platform | Version | Automation Method |
|----------|---------|-------------------|
| iOS Simulator | All versions | mobilecli + iOS Device Kit |
| Physical iOS | iOS 13+ | WebDriverAgent via go-ios |
| Real Device (debug) | iOS 13+ | USB tunnel + WDA |
资料来源：[src/webdriver-agent.ts:20-30]()
## Related Documentation
- [Main README](https://github.com/mobile-next/mobile-mcp)
- [Wiki Home](https://github.com/mobile-next/mobile-mcp/wiki)
- [Setup Guide](https://github.com/mobile-next/mobile-mcp/wiki/Setup)
- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki/Debugging)
- [Prompt Examples](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)
---
---
## Doramagic 踩坑日志
项目：mobile-next/mobile-mcp
摘要：发现 20 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback。
## 1. 配置坑 · 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_dbf2449bab944bc99876270f1ec05c62 | https://github.com/mobile-next/mobile-mcp/issues/322 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 2. 配置坑 · 来源证据：mobile_type_keys not support Chinese words
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mobile_type_keys not support Chinese words
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2dc233de12994981b510eaee492c2389 | https://github.com/mobile-next/mobile-mcp/issues/238 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安全/权限坑 · 来源证据：Default-on telemetry creates security and compliance risk for enterprise users
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Default-on telemetry creates security and compliance risk for enterprise users
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5f969914c2b845edae80052061f7b4c3 | https://github.com/mobile-next/mobile-mcp/issues/330 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安全/权限坑 · 来源证据：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0a003bada38d4c7b85ace117a1057fba | https://github.com/mobile-next/mobile-mcp/issues/323 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 5. 配置坑 · 来源证据：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0cfa3373dd3042f885f3bfc06594d58b | https://github.com/mobile-next/mobile-mcp/issues/321 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 6. 能力坑 · 来源证据：mobile fleet documentation link broken
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：mobile fleet documentation link broken
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b92402a79ce24b41b5f9ca2351e56e81 | https://github.com/mobile-next/mobile-mcp/issues/328 | 来源类型 github_issue 暴露的待验证使用条件。
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | README/documentation is current enough for a first validation pass.
## 8. 维护坑 · 来源证据：Version 0.0.49
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.49
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_885b7e8395a34cc8aaa7ce492d0b5d31 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 维护坑 · 来源证据：Version 0.0.54
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.54
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_02193405127b48d2a7d25148f61b2e9b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 | 来源类型 github_release 暴露的待验证使用条件。
## 10. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | last_activity_observed missing
## 11. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium
## 12. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium
## 13. 安全/权限坑 · 来源证据：Version 0.0.45
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.45
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e5939588c2f74a4f8e7ae874c9fee9f2 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.45 | 来源类型 github_release 暴露的待验证使用条件。
## 14. 安全/权限坑 · 来源证据：Version 0.0.47
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.47
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6f22eab42c4140bf9692e3ff9f80dc62 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.47 | 来源类型 github_release 暴露的待验证使用条件。
## 15. 安全/权限坑 · 来源证据：Version 0.0.48
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.48
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4e414a95529d4f27bb06648558502daa | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.48 | 来源类型 github_release 暴露的待验证使用条件。
## 16. 安全/权限坑 · 来源证据：Version 0.0.51
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.51
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_eca0ad1c1f574a52897db27953196b98 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51 | 来源类型 github_release 暴露的待验证使用条件。
## 17. 安全/权限坑 · 来源证据：Version 0.0.52
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.52
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0c0b172807554ff4b1969c4fff8abf4b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.52 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 18. 安全/权限坑 · 来源证据：Version 0.0.53
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.53
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c0fb42201cf24850bcd4fa91470e2042 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.53 | 来源类型 github_release 暴露的待验证使用条件。
## 19. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | issue_or_pr_quality=unknown
## 20. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | release_recency=unknown