## File: README.ja.md
# Mobile Next - モバイル開発・自動化のための MCP サーバー | iOS、Android、シミュレーター、エミュレーター、実機
[English](README.md) | **日本語** | [简体中文](README.zh-CN.md)
これは MCP サーバーです。プラットフォームに依存しないインターフェースを通じて、スケーラブルなモバイル自動化と開発を可能にし、iOS や Android の個別知識を不要にします。エミュレーター、シミュレーター、実機（iOS および Android）で実行できます。
このサーバーにより、エージェントや LLM は、構造化されたアクセシビリティスナップショット、またはスクリーンショットに基づく座標タップを通じて、ネイティブの iOS / Android アプリケーションおよびデバイスを操作できます。
**Claude Code、Codex、Gemini、GitHub Copilot、Antigravity に対応** — その他 MCP 互換クライアントでも動作します。
自分のマシン上のデバイスに対して実行することも、**[Mobile Next Cloud](https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=intro)** 上の実際の iOS / Android 実機に対して実行することもできます。同じツール群を、ローカルセットアップなしで利用できます。
https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
### 主なユースケース
モバイル自動化のスケールをどのように支援するか:
- 📲 テストやデータ入力シナリオのためのネイティブアプリ自動化（iOS および Android）
- 📝 シミュレーター / エミュレーターや実機（iPhone、Samsung、Google Pixel など）を手動操作せずに実行するスクリプト化されたフローとフォーム入力
- 🧭 LLM が駆動する複数ステップのユーザージャーニーの自動化
- 👆 エージェントベースのフレームワークのための汎用的なモバイルアプリケーション操作
- 🤖 モバイル自動化やデータ抽出のユースケースにおけるエージェント間通信の実現
## 主な機能
- 🚀 **アクセシビリティ優先 — 高速かつ低コスト**: ネイティブのアクセシビリティツリーからアプリを操作します（ビジョンモデル不要、画像トークン不要）。必要な場合のみスクリーンショット + 座標にフォールバックします。
- 📱 **1 つの API であらゆるターゲットへ**: 同じツールが iOS と Android の両方で動作します — シミュレーター、エミュレーター、実機を問いません。
- 🧠 **プラットフォームの専門知識は不要**: XCUITest も Espresso もプラットフォームごとのつなぎコードも不要です。目的を伝えればエージェントが実行します。
- 🧰 **完全なデバイス制御**: タップ、スワイプ、ジェスチャー、アプリのインストール / 起動 / 終了、画面録画、ハードウェアボタン、ディープリンク、画面の向き。
- 📊 **構造化された決定的な出力**: 実際の UI 要素を読み取って構造化データを抽出し、スクリーンショットのみのアプローチにありがちな曖昧さを削減します。
- 🪞 **Claude Code でのデバイスミラーリング**: Ghostty または kitty で動作する Claude Code 向けです。プラグインをインストールして `/mobile-mirror` を実行すると、デバイスのライブ画面がサイドペインに表示され、ターミナルを離れずにタップ、文字入力、Home/Back の操作ができます。
### 🎯 対応プラットフォーム
| ターゲット | 対応 | セットアップ |
|---|:---:|---|
| iOS シミュレーター | ✅ | Xcode と起動済みのシミュレーター (`xcrun simctl`) |
| iOS 実機 | ✅ | USB 接続され、信頼済みのデバイス |
| Android エミュレーター | ✅ | Android SDK と実行中のエミュレーター (`adb`) |
| Android 実機 | ✅ | `adb` と、有効化・認可済みの USB デバッグ |
## 🔧 利用可能な MCP ツール
### デバイス管理
- **`mobile_list_available_devices`** - 利用可能なすべてのデバイス（シミュレーター、エミュレーター、実機）を一覧表示します
- **`mobile_get_screen_size`** - モバイルデバイスの画面サイズをピクセル単位で取得します
- **`mobile_get_orientation`** - デバイスの現在の画面の向きを取得します
- **`mobile_set_orientation`** - 画面の向きを変更します（縦向き / 横向き）
- **`mobile_set_location`** - デバイスが報告する GPS 位置情報を上書きする、または上書きを解除します
- **`mobile_clipboard`** - デバイスのクリップボードを読み取る、または置き換えます
### リモートデバイス（Mobile Next Cloud）
- **`mobile_login_to_cloud_provider`** - このマシンをクラウドデバイスプロバイダーで認証します（ブラウザベースのデバイスコードログイン）
- **`mobile_list_remote_devices`** - クラウドフリートから予約可能なデバイスモデルを一覧表示します
- **`mobile_allocate_remote_device`** - 物理クラウドデバイスを専有利用のために予約します
- **`mobile_release_remote_device`** - 予約済みのクラウドデバイスをフリートに返却します
### アプリ管理
- **`mobile_list_apps`** - デバイスにインストールされているすべてのアプリを一覧表示します
- **`mobile_get_foreground_app`** - 現在フォアグラウンドにあるアプリを取得します
- **`mobile_launch_app`** - パッケージ名を指定してアプリを起動します
- **`mobile_terminate_app`** - 実行中のアプリを停止・終了します
- **`mobile_install_app`** - ファイル（.apk、.ipa、.app、.zip）からアプリをインストールします
- **`mobile_uninstall_app`** - バンドル ID またはパッケージ名を指定してアプリをアンインストールします
### 画面操作
- **`mobile_take_screenshot`** - 画面に何が表示されているかを把握するためにスクリーンショットを撮影します
- **`mobile_save_screenshot`** - スクリーンショットをファイルに保存します
- **`mobile_list_elements_on_screen`** - UI 要素を座標やプロパティとともに一覧表示します
- **`mobile_click_on_screen_at_coordinates`** - 指定した x,y 座標をクリックします
- **`mobile_double_tap_on_screen`** - 指定した座標をダブルタップします
- **`mobile_long_press_on_screen_at_coordinates`** - 指定した座標を長押しします
- **`mobile_swipe_on_screen`** - 任意の方向にスワイプします（上、下、左、右）
- **`mobile_start_screen_recording`** - デバイス画面の録画をビデオファイルへ開始します
- **`mobile_stop_screen_recording`** - 実行中の画面録画を停止し、ビデオを保存します
### 入力とナビゲーション
- **`mobile_type_keys`** - フォーカスされた要素にテキストを入力します（送信の有無を選択可能）
- **`mobile_press_button`** - デバイスのボタンを押します（HOME、BACK、VOLUME_UP/DOWN、ENTER など）
- **`mobile_open_url`** - デバイスのブラウザで URL を開きます
### ログとクラッシュレポート
- **`mobile_get_device_logs`** - デバイスのライブログを収集します（Android は logcat、iOS は unified log）。ファイルへの保存も可能です
- **`mobile_list_crashes`** - デバイス上で利用可能なクラッシュレポートを一覧表示します
- **`mobile_get_crash`** - ID を指定してクラッシュレポートの全文を取得します
- **`mobile_batch_commands`** - 複数のツールを 1 回の呼び出しで順番に実行します（例: クリック、入力、クリック）。最後に画面上の要素を一覧表示することもできます
## 🏗️ Mobile MCP のアーキテクチャ
## 📚 Wiki ページ
セットアップ、設定、デバッグに関する詳細は [wiki ページ](https://github.com/mobile-next/mobile-mcp/wiki) をご覧ください。
## 前提条件
MCP をエージェントおよびモバイルデバイスに接続するために必要なもの:
- [Xcode コマンドラインツール](https://developer.apple.com/xcode/resources/)
- [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools)
- [node.js](https://nodejs.org/en/download/) v20 以上
- [MCP](https://modelcontextprotocol.io/introduction) に対応した基盤モデルまたはエージェント。例: [Claude MCP](https://modelcontextprotocol.io/quickstart/server)、[OpenAI Agent SDK](https://openai.github.io/openai-agents-python/mcp/)、[Copilot Studio](https://www.microsoft.com/en-us/microsoft-copilot/blog/copilot-studio/introducing-model-context-protocol-mcp-in-copilot-studio-simplified-integration-with-ai-apps-and-agents/)
## インストールと設定
**標準設定** はほとんどのツールで動作します:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
Amp
Amp の VS Code 拡張機能の設定画面から追加するか、`settings.json` ファイルを更新してください:
```json
"amp.mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
```
**Amp CLI:**
ターミナルで次のコマンドを実行します:
```bash
amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
```
Antigravity 2
Antigravity には MCP サーバーを追加する CLI コマンドがないため、手動で追加します。`~/.gemini/config/mcp_config.json` を編集して次を追加してください:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
Cline
Cline をセットアップするには、上記の json を MCP 設定ファイルに追加するだけです。
[詳細は wiki をご覧ください](https://github.com/mobile-next/mobile-mcp/wiki/Cline)
Claude Code
Claude Code 内でプラグインをインストールします。Mobile MCP サーバーと `/mobile-mirror` が追加されます:
```
/plugin marketplace add mobile-next/mobile-mcp
/plugin install mobile-mcp@mobile-mcp
```
`/mobile-mirror [device-id]` を実行すると、デバイスのライブ画面を表示するペインが開きます。画像をクリックするとタップ、キー入力でキーを送信でき、上部の Home、Back、App Switch、URL ボタンも使えます。画像の表示には kitty や Ghostty など、kitty グラフィックスプロトコルに対応したターミナルが必要です。
プラグインを使えない場合は、Claude Code CLI で MCP サーバーのみを追加します:
```bash
claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
```
Claude Desktop
[MCP インストールガイド](https://modelcontextprotocol.io/quickstart/user) に従い、上記の json 設定を使用してください。
Codex
Codex CLI を使って Mobile MCP サーバーを追加します:
```bash
codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
```
あるいは、設定ファイル `~/.codex/config.toml` を作成または編集して次を追加します:
```toml
[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]
```
詳細は Codex の MCP ドキュメントをご覧ください。
Copilot
Copilot CLI を使って対話的に Mobile MCP サーバーを追加します:
```text
/mcp add
```
設定ファイル `~/.copilot/mcp-config.json` を編集して次を追加することもできます:
```json
{
"mcpServers": {
"mobile-mcp": {
"type": "local",
"command": "npx",
"tools": [
"*"
],
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
```
詳細は Copilot CLI のドキュメントをご覧ください。
Cursor
#### ボタンをクリックしてインストール:
[](https://cursor.com/en/install-mcp?name=Mobile%20MCP&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2JpbGVuZXh0L21vYmlsZS1tY3BAbGF0ZXN0Il19)
#### または手動でインストール:
`Cursor Settings` -> `MCP` -> `Add new MCP Server` を開きます。名前は任意で、`command` タイプを選び、コマンドに `npx -y @mobilenext/mobile-mcp@latest` を指定します。`Edit` をクリックして設定の確認やコマンド引数の追加もできます。
Gemini CLI
Gemini CLI を使って Mobile MCP サーバーを追加します:
```bash
gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
```
Goose
#### ボタンをクリックしてインストール:
[](https://goose-docs.ai/extension?cmd=npx&arg=-y&arg=%40mobilenext%2Fmobile-mcp%40latest&id=mobile-mcp&name=Mobile%20MCP&description=Mobile%20automation%20and%20development%20for%20iOS%2C%20Android%2C%20simulators%2C%20emulators%2C%20and%20real%20devices)
#### または手動でインストール:
`Advanced settings` -> `Extensions` -> `Add custom extension` を開きます。名前は任意で、タイプに `STDIO` を選び、`command` に `npx -y @mobilenext/mobile-mcp@latest` を設定します。「Add Extension」をクリックしてください。
Kiro
MCP サーバーの[ドキュメント](https://kiro.dev/docs/mcp/)に従ってください。例えば `.kiro/settings/mcp.json` に次のように記述します:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
```
opencode
MCP サーバーのドキュメントに従ってください。例えば `~/.config/opencode/opencode.json` に次のように記述します:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mobile-mcp": {
"type": "local",
"command": [
"npx",
"@mobilenext/mobile-mcp@latest"
],
"enabled": true
}
}
}
```
Windsurf
Windsurf の設定を開き、MCP servers に移動して、`command` タイプの新しいサーバーを次の内容で追加します:
```bash
npx @mobilenext/mobile-mcp@latest
```
または、上記の標準設定を設定ファイルの `mcpServers` の下に追加してください。
[詳細は wiki をご覧ください](https://github.com/mobile-next/mobile-mcp/wiki)! 🚀
### ✅ 動作確認
サーバーの設定が完了したら、エージェントにデバイスの一覧を尋ねてみましょう:
> list available devices
実行中のシミュレーター、エミュレーター、接続済みのデバイスが返ってくるはずです。返ってくれば、Mobile MCP は正しく設定されています。リストが空の場合は、シミュレーターまたはエミュレーターが起動していることを確認してください（[前提条件](#前提条件)を参照）。さらに詳しくは [wiki](https://github.com/mobile-next/mobile-mcp/wiki) をご覧ください。
### ☁️ クラウドデバイスでスケールする
数百台規模のデバイスにスケールしたい場合は？ CI/CD パイプラインで Mobile MCP を使いたい場合は？
エージェントで次のようにプロンプトを入力してください:
```text
log in to mobile next cloud and then show me which remote devices are available to me
```
### Streamable HTTP サーバーモード
Mobile MCP はデフォルトで stdio 上で動作します。代わりに [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) サーバーを起動するには、`--listen` フラグを使用します:
```bash
npx @mobilenext/mobile-mcp@latest --listen 3000
```
これは `localhost:3000` にバインドします。特定のインターフェースにバインドするには:
```bash
npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000
```
その後、MCP クライアントが `http://:3000/mcp`（TLS 配下なら `https://…/mcp`）に接続するよう設定します。エンドポイントは Streamable HTTP（`/mcp` への `POST`）を受け付けます。リモートモードは **ステートレス** で（セッション親和性不要）、Smithery などの水平スケールするホストとも相性が良いです。
> **移行メモ:** 以前の `--listen` は非推奨の HTTP+SSE を `/mcp` で提供していました。クライアントは `http(s)://host:port/mcp` に対して Streamable HTTP を使う必要があります。以前の純粋な SSE フローは `/mcp` では利用できなくなりました。
localhost にバインドする場合、Host ヘッダーによる DNS リバインディング保護が自動的に有効になります。
#### 認可
HTTP サーバーで Bearer トークンによる認可を要求するには、環境変数 `MOBILEMCP_AUTH` を設定します:
```bash
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
設定すると、すべてのリクエストにヘッダー `Authorization: Bearer my-secret-token` を含める必要があります。未設定の場合は認証なしで受け付け、警告を出力します。
### 🛠️ 使い方
IDE / クライアントに MCP サーバーを追加したら、AI アシスタントに対して利用可能なツールを使うよう指示できます。
例えば Cursor のエージェントモードでは、以下のプロンプトを使って UI 操作の検証・テスト・改善を素早く行ったり、画面から情報を読み取ったり、複雑なワークフローを実行したりできます。
具体的に、要点を押さえて記述してください。
### ✨ プロンプト例
#### ワークフロー
1 つのプロンプトで詳細なワークフローを指定し、ビジネスロジックを検証したり、自動化を構築したりできます。かなり大胆な指示も可能です:
**動画を検索し、コメント、いいね、共有する**
```
Find the video called " Beginner Recipe for Tonkotsu Ramen" by Way of
Ramen, click on like video, after liking write a comment " this was
delicious, will make it next Friday", share the video with the first
contact in your whatsapp list.
```
**人気の歩数計アプリをダウンロードし、登録し、ワークアウトを設定して 5 つ星を付ける**
```
Find and Download a free "Pomodoro" app that has more than 1k stars.
Launch the app, register with my email, after registration find how to
start a pomodoro timer. When the pomodoro timer started, go back to the
app store and rate the app 5 stars, and leave a comment how useful the
app is.
```
**Substack で検索し、記事を読み、ハイライト、コメント、保存する**
```
Open Substack website, search for "Latest trends in AI automation 2025",
open the first article, highlight the section titled "Emerging AI trends",
and save article to reading list for later review, comment a random
paragraph summary.
```
**ワークアウトのクラスを予約し、タイマーを設定する**
```
Open ClassPass, search for yoga classes tomorrow morning within 2 miles,
book the highest-rated class at 7 AM, confirm reservation,
setup a timer for the booked slot in the phone
```
**地域のイベントを探し、カレンダーに予定を登録する**
```
Open Eventbrite, search for AI startup meetup events happening this
weekend in "Austin, TX", select the most popular one, register and RSVP
yes to the event, setup a calendar event as a reminder.
```
**天気予報を確認し、Whatsapp / Telegram / Slack でメッセージを送る**
```
Open Weather app, check tomorrow's weather forecast for "Berlin", and
send the summary via Whatsapp/Telegram/Slack to contact "Lauren Trown",
thumbs up their response.
```
- **Zoom で会議を予定し、招待をメールで共有する**
```
Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
10AM with a duration of 1 hour, copy the invitation link, and send it via
Gmail to contacts "team@example.com".
```
## 実行と設定
### 環境変数
| 変数 | 説明 | 例 |
|---|---|---|
| `MOBILEMCP_AUTH` | Streamable HTTP サーバー（`--listen`）で Bearer トークンを必須にします。設定すると、すべてのリクエストが `Authorization: Bearer ` を送信する必要があります。 | `MOBILEMCP_AUTH=my-secret-token` |
| `MOBILEMCP_DISABLE_TELEMETRY` | 匿名の利用テレメトリを無効にします。 | `MOBILEMCP_DISABLE_TELEMETRY=1` |
| `MOBILEMCP_ALLOW_UNSAFE_URLS` | `mobile_open_url` が標準外の URL スキームを開くことを許可します（デフォルトではブロックされます）。 | `MOBILEMCP_ALLOW_UNSAFE_URLS=1` |
| `MOBILEMCP_LEGACY_ROBOT` | Android デバイスおよび iOS 実機に対して、従来のプラットフォーム固有のロボットを使用します。iOS シミュレーターは引き続き `mobilecli` を使用します。 | `MOBILEMCP_LEGACY_ROBOT=1` |
### シミュレーター、エミュレーター、実機
起動時、Mobile MCP は次のものに接続できます:
- macOS / Linux 上の iOS シミュレーター
- Linux / Windows / macOS 上の Android エミュレーター
- iOS または Android の実機（適切なプラットフォームツールとドライバーが必要です）
Mobile Next Mobile MCP を実行する前に、モバイルプラットフォームの SDK（Xcode、Android SDK）が正しくインストール・設定されていることを確認してください。
### テレメトリ
Mobile MCP は PostHog と Scarf を通じて匿名の利用テレメトリを収集します。無効にするには、環境変数 `MOBILEMCP_DISABLE_TELEMETRY` を設定します:
```bash
MOBILEMCP_DISABLE_TELEMETRY=1 npx @mobilenext/mobile-mcp@latest
```
json 設定の場合:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"],
"env": {
"MOBILEMCP_DISABLE_TELEMETRY": "1"
}
}
}
}
```
### シミュレーター / エミュレーターでの「ヘッドレス」モード実行
実機がマシンに接続されていない場合でも、バックグラウンドでエミュレーターまたはシミュレーターを使って Mobile MCP を実行できます。
例えば Android の場合:
1. エミュレーターを起動します（avdmanager / emulator コマンド）。
2. 必要なフラグを付けて Mobile MCP を実行します。
iOS の場合は、Xcode が必要で、そのシミュレーターインスタンスで Mobile MCP を使う前に Simulator を起動しておく必要があります。
- `xcrun simctl list`
- `xcrun simctl boot "iPhone 16"`
## 🧩 Mobile Next の一部として
Mobile MCP は、実際のモバイルデバイスを動かすためのツールキットの 1 つです:
- **[mobilewright](https://github.com/mobile-next/mobilewright)** — 「モバイル版 Playwright」。エージェント主導の探索を iOS / Android 向けの**再現可能で決定的なテスト**に変える準備ができたら、mobilewright へ進みましょう。
- **[mobilecli](https://github.com/mobile-next/mobilecli)** — Mobile MCP が土台としている汎用デバイス CLI。コマンドラインまたは JSON-RPC API から、デバイス、シミュレーター、エミュレーターを制御できます。
- **[Mobile Next Cloud](https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=part-of-mobile-next)** — 同じスタックをレンタルで。実際の iOS / Android 実機をオンデマンドで利用できます。エージェントに `log in to mobile next cloud and then show me which remote devices are available to me` とプロンプトを送るだけで始められます。
## 🚀 ロードマップ
Mobile MCP は継続的に改善しています。次に何を作っているかは [ROADMAP.md](ROADMAP.md) をご覧ください。優先順位はコミュニティのフィードバックに大きく影響されるため、見たいものをぜひ教えてください。
## 🤝 コントリビュート
コード、ドキュメント、バグ報告、アイデア — あらゆるコントリビュートを歓迎します。
- ⭐ **[リポジトリにスターを付ける](https://github.com/mobile-next/mobile-mcp)** — Mobile MCP を他の人に知ってもらう最も簡単な方法です。
- ビルド、テスト、プルリクエストの作成方法については [CONTRIBUTING.md](CONTRIBUTING.md) をお読みください。
- 取り組めるものを探すには [オープンな issue](https://github.com/mobile-next/mobile-mcp/issues) をご覧ください。
- 質問やアイデアは [Slack コミュニティ](https://mobilenext.ai/join-slack?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=contributing) でも歓迎します。
[行動規範](CODE_OF_CONDUCT.md)にも目を通してください。
# すべてのコントリビューターに感謝します ❤️
### このプロジェクトの改善に協力してくださったすべての方に感謝します。
## プライバシーポリシー
Mobile MCP はローカルで実行され、接続したデバイスとのみ通信します。
データの収集、利用、保持、連絡先については、Mobile Next のプライバシーポリシー
https://mobilenext.ai/privacy をご覧ください。
---
## File: README.md
# Mobile Next - MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices
**English** | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
This is an MCP Server that enables scalable mobile automation, development through a platform-agnostic interface, eliminating the need for distinct iOS or Android knowledge. You can run it on emulators, simulators, and real devices (iOS and Android).
This server allows Agents and LLMs to interact with native iOS/Android applications and devices through structured accessibility snapshots or coordinate-based taps based on screenshots.
**Works with Claude Code, Codex, Gemini, GitHub Copilot, Antigravity** — or any MCP-compatible client.
Run it against devices on your own machine, or against real iOS and Android devices in the cloud with **[Mobile Next Cloud](https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=intro)** — same tools, no local setup.
https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
### Main use cases
How we help to scale mobile automation:
- 📲 Native app automation (iOS and Android) for testing or data-entry scenarios.
- 📝 Scripted flows and form interactions without manually controlling simulators/emulators or real devices (iPhone, Samsung, Google Pixel etc)
- 🧭 Automating multi-step user journeys driven by an LLM
- 👆 General-purpose mobile application interaction for agent-based frameworks
- 🤖 Enables agent-to-agent communication for mobile automation usecases, data extraction
## Main Features
- 🚀 **Accessibility-first — fast and cheap**: drives apps from the native accessibility tree (no vision model, no image tokens), falling back to screenshots + coordinates only when needed.
- 📱 **One API, every target**: the same tools work across iOS and Android — simulators, emulators, and real devices.
- 🧠 **No platform expertise required**: no XCUITest, no Espresso, no per-platform glue — describe the goal and the agent does it.
- 🧰 **Full device control**: taps, swipes, and gestures; app install/launch/terminate; screen recording; hardware buttons; deep links; orientation.
- 📊 **Structured, deterministic output**: reads real UI elements and extracts structured data, cutting the ambiguity of screenshot-only approaches.
- 🪞 **Device mirroring in Claude Code**: for Claude Code running in Ghostty or kitty. Install the plugin and run `/mobile-mirror` to see the device's live screen in a side pane, then tap, type and press Home/Back without leaving the terminal.
### 🎯 Platform Support
| Target | Supported | Setup |
|---|:---:|---|
| iOS Simulator | ✅ | Xcode + a booted simulator (`xcrun simctl`) |
| iOS Real Device | ✅ | Device connected over USB and trusted |
| Android Emulator | ✅ | Android SDK + running emulator (`adb`) |
| Android Real Device | ✅ | `adb` + USB debugging enabled & authorized |
## 🔧 Available MCP Tools
### Device Management
- **`mobile_list_available_devices`** - List all available devices (simulators, emulators, and real devices)
- **`mobile_get_screen_size`** - Get the screen size of the mobile device in pixels
- **`mobile_get_orientation`** - Get the current screen orientation of the device
- **`mobile_set_orientation`** - Change the screen orientation (portrait/landscape)
- **`mobile_fold_device`** - Fold or unfold a foldable device (iPhone Duo simulators, foldable Android emulators)
- **`mobile_set_location`** - Override the GPS location reported by the device, or clear the override
- **`mobile_clipboard`** - Read or replace the device clipboard
### Remote Devices (Mobile Next Cloud)
- **`mobile_login_to_cloud_provider`** - Authenticate this machine with the cloud device provider (browser-based device-code login)
- **`mobile_list_remote_devices`** - List device models available to reserve from the cloud fleet
- **`mobile_allocate_remote_device`** - Reserve a physical cloud device for exclusive use
- **`mobile_release_remote_device`** - Release a reserved cloud device back to the fleet
### App Management
- **`mobile_list_apps`** - List all installed apps on the device
- **`mobile_get_foreground_app`** - Get the app currently in the foreground
- **`mobile_launch_app`** - Launch an app using its 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 by its package name or bundle ID
### Screen Interaction
- **`mobile_take_screenshot`** - Take a screenshot to understand what's on screen
- **`mobile_save_screenshot`** - Save a screenshot to a file
- **`mobile_list_elements_on_screen`** - List UI elements with their coordinates and properties
- **`mobile_click_on_screen_at_coordinates`** - Click at specific x,y coordinates or on an element by its ref
- **`mobile_double_tap_on_screen`** - Double-tap at specific coordinates or on an element by its ref
- **`mobile_long_press_on_screen_at_coordinates`** - Long press at specific coordinates or on an element by its ref
- **`mobile_swipe_on_screen`** - Swipe in any direction (up, down, left, right)
- **`mobile_start_screen_recording`** - Start recording the device screen to a video file
- **`mobile_stop_screen_recording`** - Stop the active screen recording and save the video
### Input & Navigation
- **`mobile_type_keys`** - Type text into focused elements with optional submit
- **`mobile_press_button`** - Press device buttons (HOME, BACK, VOLUME_UP/DOWN, ENTER, etc.)
- **`mobile_open_url`** - Open http/https URLs in the device browser
### Logs & Crash Reports
- **`mobile_get_device_logs`** - Collect live device logs (logcat on Android, unified log on iOS), optionally saved to a file
- **`mobile_list_crashes`** - List crash reports available on the device
- **`mobile_get_crash`** - Get the full content of a crash report by its ID
- **`mobile_batch_commands`** - Run multiple tools in sequence in a single call (e.g. click, type, click), optionally listing screen elements at the end
## 🏗️ Mobile MCP Architecture
## 📚 Wiki page
More details in our [wiki page](https://github.com/mobile-next/mobile-mcp/wiki) for setup, configuration and debugging related questions.
## Prerequisites
What you will need to connect MCP with your agent and mobile devices:
- [Xcode command line tools](https://developer.apple.com/xcode/resources/)
- [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools)
- [node.js](https://nodejs.org/en/download/) v20+
- [MCP](https://modelcontextprotocol.io/introduction) supported foundational models or agents, like [Claude MCP](https://modelcontextprotocol.io/quickstart/server), [OpenAI Agent SDK](https://openai.github.io/openai-agents-python/mcp/), [Copilot Studio](https://www.microsoft.com/en-us/microsoft-copilot/blog/copilot-studio/introducing-model-context-protocol-mcp-in-copilot-studio-simplified-integration-with-ai-apps-and-agents/)
## Installation and configuration
**Standard config** works in most of the tools:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
Amp
Add via the Amp VS Code extension settings screen or by updating your `settings.json` file:
```json
"amp.mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
```
**Amp CLI:**
Run the following command in your terminal:
```bash
amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
```
Antigravity 2
Antigravity doesn't have a CLI command to add MCP servers, so add it manually. Edit `~/.gemini/config/mcp_config.json` and add:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
Cline
To setup Cline, just add the json above to your MCP settings file.
[More in our wiki](https://github.com/mobile-next/mobile-mcp/wiki/Cline)
Claude Code
Install the plugin from inside Claude Code. It adds the Mobile MCP server and `/mobile-mirror`:
```
/plugin marketplace add mobile-next/mobile-mcp
/plugin install mobile-mcp@mobile-mcp
```
`/mobile-mirror [device-id]` opens a pane with the device's live screen. Click the picture to tap, type to send keys, and use the Home, Back, App Switch and URL buttons above it. The picture needs a terminal with the kitty graphics protocol, such as kitty or Ghostty.
If you can't use plugins, add only the MCP server with the Claude Code CLI:
```bash
claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
```
Claude Desktop
Follow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user), use json configuration above.
Codex
Use the Codex CLI to add the Mobile MCP server:
```bash
codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
```
Alternatively, create or edit the configuration file `~/.codex/config.toml` and add:
```toml
[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]
```
For more information, see the Codex MCP documentation.
Copilot
Use the Copilot CLI to interactively add the Mobile MCP server:
```text
/mcp add
```
You can edit the configuration file `~/.copilot/mcp-config.json` and add:
```json
{
"mcpServers": {
"mobile-mcp": {
"type": "local",
"command": "npx",
"tools": [
"*"
],
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
```
For more information, see the Copilot CLI documentation.
Cursor
#### Click the button to install:
[](https://cursor.com/en/install-mcp?name=Mobile%20MCP&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2JpbGVuZXh0L21vYmlsZS1tY3BAbGF0ZXN0Il19)
#### Or install manually:
Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx -y @mobilenext/mobile-mcp@latest`. You can also verify config or add command like arguments via clicking `Edit`.
Gemini CLI
Use the Gemini CLI to add the Mobile MCP server:
```bash
gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
```
Goose
#### Click the button to install:
[](https://goose-docs.ai/extension?cmd=npx&arg=-y&arg=%40mobilenext%2Fmobile-mcp%40latest&id=mobile-mcp&name=Mobile%20MCP&description=Mobile%20automation%20and%20development%20for%20iOS%2C%20Android%2C%20simulators%2C%20emulators%2C%20and%20real%20devices)
#### Or install manually:
Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx -y @mobilenext/mobile-mcp@latest`. Click "Add Extension".
Kiro
Follow the MCP Servers [documentation](https://kiro.dev/docs/mcp/). For example in `.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
```
opencode
Follow the MCP Servers documentation. For example in `~/.config/opencode/opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mobile-mcp": {
"type": "local",
"command": [
"npx",
"@mobilenext/mobile-mcp@latest"
],
"enabled": true
}
}
}
```
Windsurf
Open Windsurf settings, navigate to MCP servers, and add a new server using the `command` type with:
```bash
npx @mobilenext/mobile-mcp@latest
```
Or add the standard config under `mcpServers` in your settings as shown above.
[Read more in our wiki](https://github.com/mobile-next/mobile-mcp/wiki)! 🚀
### ✅ Verify it works
Once the server is configured, ask your agent to list devices:
> list available devices
You should get back your running simulators, emulators, and connected devices. If you do, Mobile MCP is wired up correctly. If the list is empty, make sure a simulator or emulator is running (see [Prerequisites](#prerequisites)) — for more help, check the [wiki](https://github.com/mobile-next/mobile-mcp/wiki).
### ☁️ Scale up, use a cloud device
Want to scale to hundreds of devices? Use Mobile MCP in your CI/CD pipeline?
In your Agent, prompt:
```text
log in to mobile next cloud and then show me which remote devices are available to me
```
### Streamable HTTP Server Mode
By default, Mobile MCP runs over stdio. To start a [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) server instead, use the `--listen` flag:
```bash
npx @mobilenext/mobile-mcp@latest --listen 3000
```
This binds to `localhost:3000`. To bind to a specific interface:
```bash
npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000
```
Then configure your MCP client to connect to `http://:3000/mcp` (or `https://…/mcp` behind TLS). The endpoint accepts Streamable HTTP (`POST` on `/mcp`); remote mode is **stateless** (no session affinity required), which works well with Smithery and other horizontal hosts.
> **Migration note:** `--listen` previously served the deprecated HTTP+SSE transport on `/mcp`. Clients must use Streamable HTTP against `http(s)://host:port/mcp`. The old pure-SSE flow on `/mcp` is no longer available.
When binding to localhost, Host-header DNS rebinding protection is enabled automatically.
#### Authorization
To require Bearer token authorization on the HTTP server, set the `MOBILEMCP_AUTH` environment variable:
```bash
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
When set, all requests must include the header `Authorization: Bearer my-secret-token`. When unset, the server accepts unauthenticated connections and logs a warning.
### 🛠️ How to Use
After adding the MCP server to your IDE/Client, you can instruct your AI assistant to use the available tools.
For example, in Cursor's agent mode, you could use the prompts below to quickly validate, test and iterate on UI interactions, read information from screen, go through complex workflows.
Be descriptive, straight to the point.
### ✨ Example Prompts
#### Workflows
You can specify detailed workflows in a single prompt, verify business logic, setup automations. You can go crazy:
**Search for a video, comment, like and share it.**
```
Find the video called " Beginner Recipe for Tonkotsu Ramen" by Way of
Ramen, click on like video, after liking write a comment " this was
delicious, will make it next Friday", share the video with the first
contact in your whatsapp list.
```
**Download a successful step counter app, register, setup workout and 5-star the app**
```
Find and Download a free "Pomodoro" app that has more than 1k stars.
Launch the app, register with my email, after registration find how to
start a pomodoro timer. When the pomodoro timer started, go back to the
app store and rate the app 5 stars, and leave a comment how useful the
app is.
```
**Search in Substack, read, highlight, comment and save an article**
```
Open Substack website, search for "Latest trends in AI automation 2025",
open the first article, highlight the section titled "Emerging AI trends",
and save article to reading list for later review, comment a random
paragraph summary.
```
**Reserve a workout class, set timer**
```
Open ClassPass, search for yoga classes tomorrow morning within 2 miles,
book the highest-rated class at 7 AM, confirm reservation,
setup a timer for the booked slot in the phone
```
**Find a local event, setup calendar event**
```
Open Eventbrite, search for AI startup meetup events happening this
weekend in "Austin, TX", select the most popular one, register and RSVP
yes to the event, setup a calendar event as a reminder.
```
**Check weather forecast and send a Whatsapp/Telegram/Slack message**
```
Open Weather app, check tomorrow's weather forecast for "Berlin", and
send the summary via Whatsapp/Telegram/Slack to contact "Lauren Trown",
thumbs up their response.
```
- **Schedule a meeting in Zoom and share invite via email**
```
Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
10AM with a duration of 1 hour, copy the invitation link, and send it via
Gmail to contacts "team@example.com".
```
## Running & configuration
### Environment variables
| Variable | Description | Example |
|---|---|---|
| `MOBILEMCP_AUTH` | Require a Bearer token on the Streamable HTTP server (`--listen`) — every request must then send `Authorization: Bearer `. | `MOBILEMCP_AUTH=my-secret-token` |
| `MOBILEMCP_DISABLE_TELEMETRY` | Disable anonymous usage telemetry. | `MOBILEMCP_DISABLE_TELEMETRY=1` |
| `MOBILEMCP_ALLOW_UNSAFE_URLS` | Allow `mobile_open_url` to open non-standard URL schemes (blocked by default). | `MOBILEMCP_ALLOW_UNSAFE_URLS=1` |
| `MOBILEMCP_LEGACY_ROBOT` | Use the legacy platform-specific robots for Android devices and physical iOS devices. iOS simulators continue to use `mobilecli`. | `MOBILEMCP_LEGACY_ROBOT=1` |
### Simulators, Emulators, and Real Devices
When launched, Mobile MCP can connect to:
- iOS Simulators on macOS/Linux
- Android Emulators on Linux/Windows/macOS
- iOS or Android real devices (requires proper platform tools and drivers)
Make sure you have your mobile platform SDKs (Xcode, Android SDK) installed and configured properly before running Mobile Next Mobile MCP.
### Telemetry
Mobile MCP collects anonymous usage telemetry via PostHog and Scarf. To disable it, set the `MOBILEMCP_DISABLE_TELEMETRY` environment variable:
```bash
MOBILEMCP_DISABLE_TELEMETRY=1 npx @mobilenext/mobile-mcp@latest
```
For json configurations:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"],
"env": {
"MOBILEMCP_DISABLE_TELEMETRY": "1"
}
}
}
}
```
### Running in "headless" mode on Simulators/Emulators
When you do not have a real device connected to your machine, you can run Mobile MCP with an emulator or simulator in the background.
For example, on Android:
1. Start an emulator (avdmanager / emulator command).
2. Run Mobile MCP with the desired flags
On iOS, you'll need Xcode and to run the Simulator before using Mobile MCP with that simulator instance.
- `xcrun simctl list`
- `xcrun simctl boot "iPhone 16"`
## 🧩 Part of Mobile Next
Mobile MCP is one piece of a toolkit for driving real mobile devices:
- **[mobilewright](https://github.com/mobile-next/mobilewright)** — "Playwright for mobile." When you're ready to turn agent-driven exploration into **repeatable, deterministic tests** for iOS and Android, graduate to mobilewright.
- **[mobilecli](https://github.com/mobile-next/mobilecli)** — the universal device CLI that Mobile MCP is built on: control devices, simulators, and emulators from the command line or a JSON-RPC API.
- **[Mobile Next Cloud](https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=part-of-mobile-next)** — the same stack, rented: real iOS and Android devices on demand. Just prompt your agent: `log in to mobile next cloud and then show me which remote devices are available to me` to get started.
## 🚀 Roadmap
We're continuously improving Mobile MCP. See what we're building next in [ROADMAP.md](ROADMAP.md) — priorities are shaped heavily by community feedback, so tell us what you'd like to see.
## 🤝 Contributing
Contributions are welcome — code, docs, bug reports, and ideas.
- ⭐ **[Star the repo](https://github.com/mobile-next/mobile-mcp)** — the easiest way to help others discover Mobile MCP.
- Read [CONTRIBUTING.md](CONTRIBUTING.md) for how to build, test, and open a pull request.
- Browse [open issues](https://github.com/mobile-next/mobile-mcp/issues) to find something to work on.
- Questions and ideas are also welcome in our [Slack community](https://mobilenext.ai/join-slack?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=contributing).
Please also review our [Code of Conduct](CODE_OF_CONDUCT.md).
# Thanks to all contributors ❤️
### We appreciate everyone who has helped improve this project.
## Privacy Policy
Mobile MCP runs locally and communicates only with the devices you connect.
See the Mobile Next privacy policy at https://mobilenext.ai/privacy for data
collection, usage, retention, and contact information.
---
## File: README.zh-CN.md
# Mobile Next - 用于移动开发与自动化的 MCP 服务器 | iOS、Android、模拟器、仿真器与真机
[English](README.md) | [日本語](README.ja.md) | **简体中文**
这是一个 MCP 服务器，它通过与平台无关的接口实现可扩展的移动自动化与开发，让你无需掌握 iOS 或 Android 的专门知识。你可以在仿真器、模拟器以及真机（iOS 和 Android）上运行它。
该服务器让智能体和 LLM 能够通过结构化的无障碍（accessibility）快照，或基于截图的坐标点击，来与原生 iOS/Android 应用和设备交互。
**支持 Claude Code、Codex、Gemini、GitHub Copilot、Antigravity** —— 以及任何兼容 MCP 的客户端。
你可以在自己机器上的设备运行它，也可以通过 **[Mobile Next Cloud](https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=intro)** 在云端真实 iOS 和 Android 设备上运行 —— 工具完全相同，无需本地环境配置。
https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
### 主要使用场景
我们如何帮助你扩展移动自动化:
- 📲 面向测试或数据录入场景的原生应用自动化（iOS 和 Android）
- 📝 无需手动操作模拟器/仿真器或真机（iPhone、三星、Google Pixel 等）即可执行的脚本化流程与表单交互
- 🧭 由 LLM 驱动的多步骤用户旅程自动化
- 👆 面向智能体框架的通用移动应用交互能力
- 🤖 为移动自动化和数据提取场景提供智能体之间的通信能力
## 主要特性
- 🚀 **无障碍优先 —— 快速且低成本**: 基于原生无障碍树驱动应用（无需视觉模型，不消耗图像 token），仅在必要时回退到截图 + 坐标方式。
- 📱 **一套 API，覆盖所有目标**: 同一套工具同时适用于 iOS 和 Android —— 模拟器、仿真器和真机皆可。
- 🧠 **无需平台专业知识**: 不需要 XCUITest，不需要 Espresso，也不需要各平台的胶水代码 —— 描述目标，智能体来完成。
- 🧰 **完整的设备控制**: 点击、滑动与手势；应用安装/启动/终止；屏幕录制；硬件按键；深度链接；屏幕方向。
- 📊 **结构化、确定性的输出**: 读取真实的 UI 元素并提取结构化数据，减少纯截图方案带来的歧义。
- 🪞 **在 Claude Code 中镜像设备**: 适用于在 Ghostty 或 kitty 中运行的 Claude Code。安装插件后运行 `/mobile-mirror`，即可在侧边窗格中查看设备的实时画面，并且无需离开终端就能点按、输入文字以及按 Home/Back。
### 🎯 平台支持
| 目标 | 是否支持 | 环境准备 |
|---|:---:|---|
| iOS 模拟器 | ✅ | Xcode 以及已启动的模拟器 (`xcrun simctl`) |
| iOS 真机 | ✅ | 通过 USB 连接并已信任的设备 |
| Android 仿真器 | ✅ | Android SDK 以及运行中的仿真器 (`adb`) |
| Android 真机 | ✅ | `adb`，并已启用并授权 USB 调试 |
## 🔧 可用的 MCP 工具
### 设备管理
- **`mobile_list_available_devices`** - 列出所有可用设备（模拟器、仿真器和真机）
- **`mobile_get_screen_size`** - 获取移动设备的屏幕尺寸（像素）
- **`mobile_get_orientation`** - 获取设备当前的屏幕方向
- **`mobile_set_orientation`** - 更改屏幕方向（竖屏/横屏）
- **`mobile_set_location`** - 覆盖设备上报的 GPS 位置，或清除该覆盖
- **`mobile_clipboard`** - 读取或替换设备剪贴板内容
### 远程设备（Mobile Next Cloud）
- **`mobile_login_to_cloud_provider`** - 将本机与云设备提供方进行认证（基于浏览器的设备码登录）
- **`mobile_list_remote_devices`** - 列出可从云设备池中预约的设备型号
- **`mobile_allocate_remote_device`** - 预约一台物理云设备以供独占使用
- **`mobile_release_remote_device`** - 将已预约的云设备释放回设备池
### 应用管理
- **`mobile_list_apps`** - 列出设备上已安装的所有应用
- **`mobile_get_foreground_app`** - 获取当前处于前台的应用
- **`mobile_launch_app`** - 使用包名启动应用
- **`mobile_terminate_app`** - 停止并终止正在运行的应用
- **`mobile_install_app`** - 从文件安装应用（.apk、.ipa、.app、.zip）
- **`mobile_uninstall_app`** - 使用 bundle ID 或包名卸载应用
### 屏幕交互
- **`mobile_take_screenshot`** - 截取屏幕截图以了解屏幕上的内容
- **`mobile_save_screenshot`** - 将截图保存为文件
- **`mobile_list_elements_on_screen`** - 列出 UI 元素及其坐标和属性
- **`mobile_click_on_screen_at_coordinates`** - 点击指定的 x,y 坐标
- **`mobile_double_tap_on_screen`** - 双击指定坐标
- **`mobile_long_press_on_screen_at_coordinates`** - 长按指定坐标
- **`mobile_swipe_on_screen`** - 向任意方向滑动（上、下、左、右）
- **`mobile_start_screen_recording`** - 开始将设备屏幕录制为视频文件
- **`mobile_stop_screen_recording`** - 停止当前的屏幕录制并保存视频
### 输入与导航
- **`mobile_type_keys`** - 向获得焦点的元素输入文本，可选择是否提交
- **`mobile_press_button`** - 按下设备按键（HOME、BACK、VOLUME_UP/DOWN、ENTER 等）
- **`mobile_open_url`** - 在设备浏览器中打开 URL
### 日志与崩溃报告
- **`mobile_get_device_logs`** - 采集设备实时日志（Android 上为 logcat，iOS 上为 unified log），可选择保存到文件
- **`mobile_list_crashes`** - 列出设备上可用的崩溃报告
- **`mobile_get_crash`** - 按 ID 获取崩溃报告的完整内容
- **`mobile_batch_commands`** - 在一次调用中按顺序运行多个工具（例如点击、输入、点击），可选择在最后列出屏幕元素
## 🏗️ Mobile MCP 架构
## 📚 Wiki 页面
关于安装、配置和调试的更多细节，请查看我们的 [wiki 页面](https://github.com/mobile-next/mobile-mcp/wiki)。
## 前置条件
将 MCP 与你的智能体和移动设备连接起来所需要的东西:
- [Xcode 命令行工具](https://developer.apple.com/xcode/resources/)
- [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools)
- [node.js](https://nodejs.org/en/download/) v20 及以上
- 支持 [MCP](https://modelcontextprotocol.io/introduction) 的基础模型或智能体，例如 [Claude MCP](https://modelcontextprotocol.io/quickstart/server)、[OpenAI Agent SDK](https://openai.github.io/openai-agents-python/mcp/)、[Copilot Studio](https://www.microsoft.com/en-us/microsoft-copilot/blog/copilot-studio/introducing-model-context-protocol-mcp-in-copilot-studio-simplified-integration-with-ai-apps-and-agents/)
## 安装与配置
**标准配置** 适用于大多数工具:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
Amp
可以通过 Amp 的 VS Code 扩展设置界面添加，或者更新你的 `settings.json` 文件:
```json
"amp.mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
```
**Amp CLI:**
在终端中运行以下命令:
```bash
amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
```
Antigravity 2
Antigravity 没有添加 MCP 服务器的 CLI 命令，因此需要手动添加。编辑 `~/.gemini/config/mcp_config.json` 并加入:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
Cline
配置 Cline 时，只需将上面的 json 添加到你的 MCP 设置文件中即可。
[更多内容见我们的 wiki](https://github.com/mobile-next/mobile-mcp/wiki/Cline)
Claude Code
在 Claude Code 中安装插件，它会添加 Mobile MCP 服务器和 `/mobile-mirror`:
```
/plugin marketplace add mobile-next/mobile-mcp
/plugin install mobile-mcp@mobile-mcp
```
`/mobile-mirror [device-id]` 会打开一个显示设备实时画面的窗格。点击画面即可点按设备，输入文字即可发送按键，上方还有 Home、Back、App Switch 和 URL 按钮。显示画面需要支持 kitty 图形协议的终端，例如 kitty 或 Ghostty。
如果无法使用插件，可以用 Claude Code CLI 只添加 MCP 服务器:
```bash
claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
```
Claude Desktop
参照 [MCP 安装指南](https://modelcontextprotocol.io/quickstart/user)，使用上面的 json 配置。
Codex
使用 Codex CLI 添加 Mobile MCP 服务器:
```bash
codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
```
或者，创建或编辑配置文件 `~/.codex/config.toml` 并加入:
```toml
[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]
```
更多信息请参阅 Codex 的 MCP 文档。
Copilot
使用 Copilot CLI 交互式地添加 Mobile MCP 服务器:
```text
/mcp add
```
你也可以编辑配置文件 `~/.copilot/mcp-config.json` 并加入:
```json
{
"mcpServers": {
"mobile-mcp": {
"type": "local",
"command": "npx",
"tools": [
"*"
],
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
```
更多信息请参阅 Copilot CLI 文档。
Cursor
#### 点击按钮安装:
[](https://cursor.com/en/install-mcp?name=Mobile%20MCP&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2JpbGVuZXh0L21vYmlsZS1tY3BAbGF0ZXN0Il19)
#### 或手动安装:
依次进入 `Cursor Settings` -> `MCP` -> `Add new MCP Server`。名称可自定义，类型选择 `command`，命令填写 `npx -y @mobilenext/mobile-mcp@latest`。你也可以点击 `Edit` 来核对配置或添加命令行参数。
Gemini CLI
使用 Gemini CLI 添加 Mobile MCP 服务器:
```bash
gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
```
Goose
#### 点击按钮安装:
[](https://goose-docs.ai/extension?cmd=npx&arg=-y&arg=%40mobilenext%2Fmobile-mcp%40latest&id=mobile-mcp&name=Mobile%20MCP&description=Mobile%20automation%20and%20development%20for%20iOS%2C%20Android%2C%20simulators%2C%20emulators%2C%20and%20real%20devices)
#### 或手动安装:
依次进入 `Advanced settings` -> `Extensions` -> `Add custom extension`。名称可自定义，类型选择 `STDIO`，并将 `command` 设为 `npx -y @mobilenext/mobile-mcp@latest`。然后点击 “Add Extension”。
Kiro
请参照 MCP 服务器[文档](https://kiro.dev/docs/mcp/)。例如在 `.kiro/settings/mcp.json` 中:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": [
"@mobilenext/mobile-mcp@latest"
]
}
}
}
```
opencode
请参照 MCP 服务器文档。例如在 `~/.config/opencode/opencode.json` 中:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mobile-mcp": {
"type": "local",
"command": [
"npx",
"@mobilenext/mobile-mcp@latest"
],
"enabled": true
}
}
}
```
Windsurf
打开 Windsurf 设置，进入 MCP servers，使用 `command` 类型添加一个新服务器:
```bash
npx @mobilenext/mobile-mcp@latest
```
或者按照上文所示，将标准配置添加到设置中的 `mcpServers` 下。
[在我们的 wiki 中了解更多](https://github.com/mobile-next/mobile-mcp/wiki)! 🚀
### ✅ 验证是否正常工作
服务器配置完成后，让你的智能体列出设备:
> list available devices
你应当会看到正在运行的模拟器、仿真器以及已连接的设备。如果能看到，说明 Mobile MCP 已正确接入。如果列表为空，请确认已经启动了模拟器或仿真器（参见[前置条件](#前置条件)）—— 需要更多帮助请查看 [wiki](https://github.com/mobile-next/mobile-mcp/wiki)。
### ☁️ 扩展规模，使用云设备
想扩展到数百台设备？想在 CI/CD 流水线中使用 Mobile MCP？
在你的智能体中输入提示词:
```text
log in to mobile next cloud and then show me which remote devices are available to me
```
### Streamable HTTP 服务器模式
Mobile MCP 默认通过 stdio 运行。若要改为启动 [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) 服务器，请使用 `--listen` 参数:
```bash
npx @mobilenext/mobile-mcp@latest --listen 3000
```
这会绑定到 `localhost:3000`。若要绑定到指定网络接口:
```bash
npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000
```
然后将你的 MCP 客户端配置为连接 `http://:3000/mcp`（TLS 后可用 `https://…/mcp`）。该端点接受 Streamable HTTP（对 `/mcp` 的 `POST`）；远程模式为 **无状态**（无需会话亲和性），非常适合 Smithery 等水平扩展的托管平台。
> **迁移说明:** 此前 `--listen` 在 `/mcp` 上提供已弃用的 HTTP+SSE。客户端需对 `http(s)://host:port/mcp` 使用 Streamable HTTP。`/mcp` 上原有的纯 SSE 流程已不再可用。
绑定到 localhost 时，会自动启用基于 Host 请求头的 DNS 重绑定防护。
#### 认证授权
若要在 HTTP 服务器上强制使用 Bearer token 授权，请设置环境变量 `MOBILEMCP_AUTH`:
```bash
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
```
设置之后，所有请求都必须包含请求头 `Authorization: Bearer my-secret-token`。未设置时接受未认证连接并输出警告。
### 🛠️ 如何使用
将 MCP 服务器添加到你的 IDE/客户端之后，你就可以指示 AI 助手使用这些可用工具。
例如在 Cursor 的 agent 模式下，你可以使用下面的提示词来快速验证、测试和迭代 UI 交互，从屏幕读取信息，或者走完复杂的流程。
描述要具体，直击要点。
### ✨ 提示词示例
#### 工作流
你可以在一条提示词中指定详细的工作流，验证业务逻辑，搭建自动化。可以尽情发挥:
**搜索视频，评论、点赞并分享**
```
Find the video called " Beginner Recipe for Tonkotsu Ramen" by Way of
Ramen, click on like video, after liking write a comment " this was
delicious, will make it next Friday", share the video with the first
contact in your whatsapp list.
```
**下载一款热门计步应用，注册、设置锻炼并给出五星好评**
```
Find and Download a free "Pomodoro" app that has more than 1k stars.
Launch the app, register with my email, after registration find how to
start a pomodoro timer. When the pomodoro timer started, go back to the
app store and rate the app 5 stars, and leave a comment how useful the
app is.
```
**在 Substack 中搜索、阅读、高亮、评论并保存文章**
```
Open Substack website, search for "Latest trends in AI automation 2025",
open the first article, highlight the section titled "Emerging AI trends",
and save article to reading list for later review, comment a random
paragraph summary.
```
**预约健身课程并设置计时器**
```
Open ClassPass, search for yoga classes tomorrow morning within 2 miles,
book the highest-rated class at 7 AM, confirm reservation,
setup a timer for the booked slot in the phone
```
**查找本地活动并创建日历事件**
```
Open Eventbrite, search for AI startup meetup events happening this
weekend in "Austin, TX", select the most popular one, register and RSVP
yes to the event, setup a calendar event as a reminder.
```
**查看天气预报并通过 Whatsapp/Telegram/Slack 发送消息**
```
Open Weather app, check tomorrow's weather forecast for "Berlin", and
send the summary via Whatsapp/Telegram/Slack to contact "Lauren Trown",
thumbs up their response.
```
- **在 Zoom 中安排会议并通过邮件分享邀请**
```
Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
10AM with a duration of 1 hour, copy the invitation link, and send it via
Gmail to contacts "team@example.com".
```
## 运行与配置
### 环境变量
| 变量 | 说明 | 示例 |
|---|---|---|
| `MOBILEMCP_AUTH` | 要求 Streamable HTTP 服务器（`--listen`）使用 Bearer token —— 设置后每个请求都必须发送 `Authorization: Bearer `。 | `MOBILEMCP_AUTH=my-secret-token` |
| `MOBILEMCP_DISABLE_TELEMETRY` | 关闭匿名使用情况遥测。 | `MOBILEMCP_DISABLE_TELEMETRY=1` |
| `MOBILEMCP_ALLOW_UNSAFE_URLS` | 允许 `mobile_open_url` 打开非标准的 URL scheme（默认被阻止）。 | `MOBILEMCP_ALLOW_UNSAFE_URLS=1` |
| `MOBILEMCP_LEGACY_ROBOT` | 对 Android 设备和 iOS 真机使用旧版的平台专用 robot。iOS 模拟器仍然使用 `mobilecli`。 | `MOBILEMCP_LEGACY_ROBOT=1` |
### 模拟器、仿真器与真机
启动后，Mobile MCP 可以连接到:
- macOS/Linux 上的 iOS 模拟器
- Linux/Windows/macOS 上的 Android 仿真器
- iOS 或 Android 真机（需要相应的平台工具和驱动）
在运行 Mobile Next Mobile MCP 之前，请确保已正确安装并配置移动平台 SDK（Xcode、Android SDK）。
### 遥测
Mobile MCP 通过 PostHog 和 Scarf 收集匿名的使用情况遥测数据。若要关闭，请设置环境变量 `MOBILEMCP_DISABLE_TELEMETRY`:
```bash
MOBILEMCP_DISABLE_TELEMETRY=1 npx @mobilenext/mobile-mcp@latest
```
对于 json 配置:
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"],
"env": {
"MOBILEMCP_DISABLE_TELEMETRY": "1"
}
}
}
}
```
### 在模拟器/仿真器上以“无头”模式运行
当你的机器上没有连接真机时，可以让 Mobile MCP 配合后台运行的仿真器或模拟器工作。
例如在 Android 上:
1. 启动一个仿真器（avdmanager / emulator 命令）。
2. 使用所需参数运行 Mobile MCP。
在 iOS 上，你需要安装 Xcode，并在通过 Mobile MCP 使用某个模拟器实例之前先启动 Simulator。
- `xcrun simctl list`
- `xcrun simctl boot "iPhone 16"`
## 🧩 Mobile Next 的一部分
Mobile MCP 是驱动真实移动设备这套工具集中的一环:
- **[mobilewright](https://github.com/mobile-next/mobilewright)** —— “移动端的 Playwright”。当你准备把智能体驱动的探索式操作变成 iOS 和 Android 上**可重复、确定性的测试**时，就该升级到 mobilewright。
- **[mobilecli](https://github.com/mobile-next/mobilecli)** —— Mobile MCP 所构建于其上的通用设备 CLI: 通过命令行或 JSON-RPC API 控制设备、模拟器和仿真器。
- **[Mobile Next Cloud](https://mobilenext.ai/cloud?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=part-of-mobile-next)** —— 同一套技术栈，按需租用: 随时可用的真实 iOS 和 Android 设备。只需向你的智能体输入提示词 `log in to mobile next cloud and then show me which remote devices are available to me` 即可开始。
## 🚀 路线图
我们持续改进 Mobile MCP。想了解我们接下来在做什么，请查看 [ROADMAP.md](ROADMAP.md) —— 优先级在很大程度上取决于社区反馈，所以请告诉我们你希望看到什么。
## 🤝 参与贡献
我们欢迎各种形式的贡献 —— 代码、文档、错误报告和想法。
- ⭐ **[给仓库点个 star](https://github.com/mobile-next/mobile-mcp)** —— 这是帮助更多人发现 Mobile MCP 最简单的方式。
- 阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何构建、测试并提交 pull request。
- 浏览[待处理的 issue](https://github.com/mobile-next/mobile-mcp/issues) 寻找可以着手的工作。
- 也欢迎在我们的 [Slack 社区](https://mobilenext.ai/join-slack?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=contributing) 中提问和分享想法。
也请阅读我们的[行为准则](CODE_OF_CONDUCT.md)。
# 感谢所有贡献者 ❤️
### 感谢每一位帮助改进这个项目的人。
## 隐私政策
Mobile MCP 在本地运行，仅与你所连接的设备通信。
有关数据收集、使用、保留以及联系方式，请查看 Mobile Next 隐私政策:
[https://mobilenext.ai/privacy](https://mobilenext.ai/privacy)。
---
## File: CHANGELOG.md
## [1.0.12](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.12) (2026-10-18)
* Feat: `mobile_get_foreground_app` reports the focused activity on Android and the view controller on iOS ([#512](https://github.com/mobile-next/mobile-mcp/pull/512))
* Fix: Large UI dumps no longer fail with `ENOBUFS` when reading mobilecli's output ([#518](https://github.com/mobile-next/mobile-mcp/pull/518)), thanks to [@whitelancefly](https://github.com/whitelancefly) and [@DanielMcSheehy](https://github.com/DanielMcSheehy)
* Fix: `mobile_swipe_on_screen` rejects a swipe that gives only one of `x` and `y`, instead of silently swiping from the center ([#477](https://github.com/mobile-next/mobile-mcp/pull/477))
* Fix(Android): Typed text starting with `#` or `~` is no longer dropped or expanded by the device shell for legacy adb ([#502](https://github.com/mobile-next/mobile-mcp/pull/502)), thanks to [@sxh313](https://github.com/sxh313)
* Chore: Upgrade mobilewright to 0.0.67 ([#517](https://github.com/mobile-next/mobile-mcp/pull/517))
## [1.0.11](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.11) (2026-10-14)
* Security: Output paths are resolved through every symlink before checking the allowed directories, so a symlink can no longer redirect a screenshot, log or recording outside them ([#506](https://github.com/mobile-next/mobile-mcp/pull/506)), thanks to [@ppjsw](https://github.com/ppjsw), [@TBernard97](https://github.com/TBernard97), [@barnessomer](https://github.com/barnessomer) and [@arpitjain099](https://github.com/arpitjain099)
* Security: Output paths with a symlink cycle or too many levels of symbolic links are rejected ([#507](https://github.com/mobile-next/mobile-mcp/pull/507)), thanks to [@TBernard97](https://github.com/TBernard97), [@barnessomer](https://github.com/barnessomer) and [@arpitjain099](https://github.com/arpitjain099)
* Security: The filesystem root and the home directory are never treated as an allowed output directory, even when the server is started from them ([#508](https://github.com/mobile-next/mobile-mcp/pull/508)), thanks to [@barnessomer](https://github.com/barnessomer)
* Security: Screenshots and device logs are written with `O_NOFOLLOW`, so a symlink planted after validation cannot redirect the write ([#509](https://github.com/mobile-next/mobile-mcp/pull/509)), thanks to [@barnessomer](https://github.com/barnessomer) and [@arpitjain099](https://github.com/arpitjain099)
* Security: Screen recordings are recorded into a private directory and moved to the output when done, never written through a symlink ([#510](https://github.com/mobile-next/mobile-mcp/pull/510)), thanks to [@barnessomer](https://github.com/barnessomer)
* Fix: `mobile_open_url` accepts a url with an upper-case scheme, such as `HTTPS://` ([#478](https://github.com/mobile-next/mobile-mcp/pull/478))
* Fix: `mobile_swipe_on_screen` rejects a non-positive swipe distance ([#499](https://github.com/mobile-next/mobile-mcp/pull/499))
* Fix: The build script works on Windows ([#501](https://github.com/mobile-next/mobile-mcp/pull/501))
* Fix: `mobile_press_button` lists every button it accepts, per platform, including `BACKSPACE`, `APP_SWITCH`, `POWER` and `LOCK` ([#500](https://github.com/mobile-next/mobile-mcp/pull/500))
* Fix(iOS): The agent is installed automatically on a simulator that does not have it yet ([#498](https://github.com/mobile-next/mobile-mcp/pull/498)), thanks to [@sxh313](https://github.com/sxh313)
* Chore: Upgrade mobilewright to 0.0.66 ([#505](https://github.com/mobile-next/mobile-mcp/pull/505))
## [1.0.10](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.10) (2026-10-11)
* Feat: Add `get_more_tools`, so an agent can report a capability mobile-mcp is missing ([#491](https://github.com/mobile-next/mobile-mcp/pull/491))
* Fix: A tool that fails with an actionable error now returns `isError: true`, instead of looking like a success ([#495](https://github.com/mobile-next/mobile-mcp/pull/495)), thanks to [@ppjsw](https://github.com/ppjsw)
* Fix: `mobile_long_press_on_screen_at_coordinates` accepts a fractional `duration`, rounding it instead of failing ([#476](https://github.com/mobile-next/mobile-mcp/pull/476))
* Fix(iOS): `mobile_list_elements_on_screen` returns elements again in legacy robot mode with current WebDriverAgent ([#496](https://github.com/mobile-next/mobile-mcp/pull/496)), thanks to [@tripleyoung](https://github.com/tripleyoung)
* Chore: Upgrade mobilewright to 0.0.65, which bundles mobilecli 1.0.19 ([#493](https://github.com/mobile-next/mobile-mcp/pull/493))
## [1.0.9](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.9) (2026-10-09)
* Feat: `mobile_list_available_devices` points to the remote cloud fleet when no local device is available, and the agent asks before using one ([#472](https://github.com/mobile-next/mobile-mcp/pull/472))
* Feat: `mobile_double_tap_on_screen` and `mobile_long_press_on_screen_at_coordinates` accept `ref`, like `mobile_click_on_screen_at_coordinates` ([#471](https://github.com/mobile-next/mobile-mcp/pull/471))
* Fix: `mobile_uninstall_app` takes `packageName` instead of `bundle_id`, matching `mobile_launch_app` and `mobile_terminate_app` ([#471](https://github.com/mobile-next/mobile-mcp/pull/471))
* Fix: `mobile_type_keys` no longer requires `submit`, it defaults to `false` ([#471](https://github.com/mobile-next/mobile-mcp/pull/471))
* Fix: Tool descriptions no longer name tools that do not exist, and `mobile_batch_commands` lists the tools it accepts as steps ([#471](https://github.com/mobile-next/mobile-mcp/pull/471))
* Fix: `mobile_get_device_logs` matches filters case-insensitively, and the message as a substring ([mobilecli#483](https://github.com/mobile-next/mobilecli/pull/483))
* Fix: `mobile_press_button` accepts button names case-insensitively ([mobilecli#479](https://github.com/mobile-next/mobilecli/pull/479))
* Fix(iOS): `mobile_terminate_app` on a simulator reports "process not found" or "not installed" instead of a simctl exit status ([mobilecli#493](https://github.com/mobile-next/mobilecli/pull/493))
* Fix(iOS): `mobile_list_crashes` lists only the simulator's own crash reports, not the host's ([mobilecli#482](https://github.com/mobile-next/mobilecli/pull/482))
* Fix(Android): The device stays in touch mode while typing text ([mobilecli#492](https://github.com/mobile-next/mobilecli/pull/492))
* Chore: Upgrade mobilewright to 0.0.64, which bundles mobilecli 1.0.18 ([#475](https://github.com/mobile-next/mobile-mcp/pull/475))
## [1.0.8](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.8) (2026-10-02)
* Feat: mobile-mcp is now a Claude Code plugin, and it brings `/mobile-mirror`: the device's live screen in a pane, where you can tap, type, and press Home/Back/App Switch, or open a URL (Claude Code in Ghostty or kitty). See the [README](https://github.com/mobile-next/mobile-mcp#installation-and-configuration) for plugin installation instructions ([#468](https://github.com/mobile-next/mobile-mcp/pull/468))
## [1.0.7](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.7) (2026-10-01)
* Fix: `server/discover` is answered for protocol revision 2026-07-28 instead of `Method not found` ([#451](https://github.com/mobile-next/mobile-mcp/pull/451), [#463](https://github.com/mobile-next/mobile-mcp/pull/463)), thanks to [@rahul05ranjan](https://github.com/rahul05ranjan)
* Fix: `mobile_list_elements_on_screen` raises an actionable error instead of a raw `TypeError` when the screen has no elements, e.g. an Android device with its screen off ([#457](https://github.com/mobile-next/mobile-mcp/pull/457)), thanks to [@Yi-111-a](https://github.com/Yi-111-a)
* Fix: `mobile_long_press_on_screen_at_coordinates` rejects a negative duration ([mobilecli#474](https://github.com/mobile-next/mobilecli/pull/474))
* Fix: No more orphan mobilecli server, signals are forwarded to the binary ([mobilecli#475](https://github.com/mobile-next/mobilecli/pull/475))
* Fix(iOS): Landscape screenshots are rotated in the pixels, not with an EXIF tag ([devicekit-ios#93](https://github.com/mobile-next/devicekit-ios/pull/93))
* Fix(iOS): `mobile_get_screen_size` reports the unfolded screen size on foldable simulators ([devicekit-ios#91](https://github.com/mobile-next/devicekit-ios/pull/91))
* Fix(iOS): Fail fast when the agent server can't start ([devicekit-ios#94](https://github.com/mobile-next/devicekit-ios/pull/94))
* Feat(iOS): `DEVICEKIT_LISTEN_HOST` accepts multiple addresses, including IPv6 ([devicekit-ios#92](https://github.com/mobile-next/devicekit-ios/pull/92)), thanks to [@hillct](https://github.com/hillct)
* Fix(Android): `mobile_open_url` keeps the whole URL, values after `&` were missing ([mobilecli#472](https://github.com/mobile-next/mobilecli/pull/472))
* Fix(Android): Stop the device server when idle or when the daemon exits, freeing uiautomator ([mobilecli#476](https://github.com/mobile-next/mobilecli/pull/476))
* Fix(Android): Quote package names passed to adb shell, preventing injection ([mobilecli#471](https://github.com/mobile-next/mobilecli/pull/471))
## [1.0.6](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.6) (2026-09-30)
* Feat: `mobile_fold_device` folds and unfolds foldable devices by posture (`folded`, `half-open`, `open`) or hinge angle; supports iPhone Duo simulators and foldable Android emulators ([#458](https://github.com/mobile-next/mobile-mcp/pull/458))
## [1.0.5](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.5) (2026-09-23)
* Feat: Server instructions telling clients to pick a device first, read the screen via `mobile_list_elements_on_screen`, batch round-trips, and release remote devices when done ([#445](https://github.com/mobile-next/mobile-mcp/pull/445))
* Fix: Recordings from `mobile_stop_screen_recording` are playable mp4s; streams with B-frames used to decode as one frame lasting hundreds of hours ([mobilecli#430](https://github.com/mobile-next/mobilecli/pull/430))
* Fix: Don't hang on a locked keyring when reading credentials; time out after 3s and continue without remote devices ([mobilecli#408](https://github.com/mobile-next/mobilecli/pull/408)), thanks to [@EnglandLobster](https://github.com/EnglandLobster)
* Perf(iOS): Stop tearing down and relaunching the agent on every call ([mobilecli#406](https://github.com/mobile-next/mobilecli/pull/406)), thanks to [@bjjeong](https://github.com/bjjeong)
* Feat(iOS): Slider, picker, alert, list and navigation elements are kept in `mobile_list_elements_on_screen` ([mobilecli#440](https://github.com/mobile-next/mobilecli/pull/440))
* Feat(iOS): `mobile_get_foreground_app` reports the on-screen view controller as the activity ([mobilecli#405](https://github.com/mobile-next/mobilecli/pull/405))
* Feat(iOS): Screenshots and screen recording can run at the same time ([mobilecli#429](https://github.com/mobile-next/mobilecli/pull/429))
* Fix(iOS): Clipboard on simulators works on iOS 26.5, where `simctl pbcopy` silently left it empty ([mobilecli#425](https://github.com/mobile-next/mobilecli/pull/425))
* Fix(iOS): Restore iOS 14 support ([devicekit-ios#75](https://github.com/mobile-next/devicekit-ios/pull/75), [devicekit-ios#76](https://github.com/mobile-next/devicekit-ios/pull/76)), thanks to [@hakanor](https://github.com/hakanor)
* Perf(Android): Tap, long press, swipe, buttons and typing go through the embedded agent instead of `adb shell input`, which forked a JVM per call ([mobilecli#412](https://github.com/mobile-next/mobilecli/pull/412)), thanks to [@akexorcist](https://github.com/akexorcist)
* Fix(Android): `mobile_get_foreground_app` reports the real app name and focused activity, including on devices with more than one display ([mobilecli#403](https://github.com/mobile-next/mobilecli/pull/403), [mobilecli#423](https://github.com/mobile-next/mobilecli/pull/423)), thanks to [@akexorcist](https://github.com/akexorcist)
* Fix(Android): `mobile_list_elements_on_screen` is no longer stale after fast content changes, such as a Compose `LazyRow` loading ([mobilecli#439](https://github.com/mobile-next/mobilecli/pull/439))
* Fix(Android): Screenshots and recording work on Android 12 and 13 ([mobilecli#435](https://github.com/mobile-next/mobilecli/pull/435))
* Fix(Android): Apps and urls launch on the default display ([mobilecli#442](https://github.com/mobile-next/mobilecli/pull/442))
* Fix(Android): Agents are reachable when the adb server runs on another host ([mobilecli#434](https://github.com/mobile-next/mobilecli/pull/434))
* Chore: Log the mobile-mcp and MCP SDK versions on stdio startup ([#445](https://github.com/mobile-next/mobile-mcp/pull/445))
* Chore: Migrate to the MCP TypeScript SDK v2 package split (`@modelcontextprotocol/server`, `/node`, `/express`); no protocol or transport change, v1 clients keep working ([#445](https://github.com/mobile-next/mobile-mcp/pull/445), based on [#400](https://github.com/mobile-next/mobile-mcp/pull/400) by [@anxkhn](https://github.com/anxkhn))
## [1.0.4](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.4) (2026-09-13)
* Feat: Serve Streamable HTTP on `--listen` at `/mcp`; the removed `/sse` endpoint now returns 410 with a migration note ([#441](https://github.com/mobile-next/mobile-mcp/pull/441))
* Fix: Every `mobile_take_screenshot` result now states how to convert positions in the screenshot into screen coordinates, so taps derived from downscaled screenshots land where intended ([#440](https://github.com/mobile-next/mobile-mcp/pull/440), closes [#29](https://github.com/mobile-next/mobile-mcp/issues/29), [#163](https://github.com/mobile-next/mobile-mcp/issues/163))
## [1.0.3](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.3) (2026-09-08)
* Feat: Add `mobile_batch_commands` tool to run several tools in one call for major performance boost ([#427](https://github.com/mobile-next/mobile-mcp/pull/427))
* Feat: Request to list elements (refresh) after commands end, to sync state ([#427](https://github.com/mobile-next/mobile-mcp/pull/427))
* Feat: Click on element by `@ref` from `mobile_list_elements_on_screen` ([#429](https://github.com/mobile-next/mobile-mcp/pull/429))
* Feat: Text format for `mobile_list_elements_on_screen`, now the default, ~5x smaller than json ([#431](https://github.com/mobile-next/mobile-mcp/pull/431))
* Feat: Add geo location, clipboard and device logs tools ([#423](https://github.com/mobile-next/mobile-mcp/pull/423))
* Feat: Add `mobile_get_foreground_app` tool ([#420](https://github.com/mobile-next/mobile-mcp/pull/420))
* Feat: Scale screenshots natively via mobilecli, drop sips/imagemagick ([#418](https://github.com/mobile-next/mobile-mcp/pull/418))
* Feat: Agent Plugin packaging, mobile-automation skill, MCPB bundle and Smithery CI ([#416](https://github.com/mobile-next/mobile-mcp/pull/416), [#415](https://github.com/mobile-next/mobile-mcp/pull/415))
* Feat: Run device commands through a background daemon over a unix socket for a major performance boost ([mobilecli#384](https://github.com/mobile-next/mobilecli/pull/384))
* Feat: Dump Flutter UI via the Dart VM service with semantics and element types ([mobilecli#365](https://github.com/mobile-next/mobilecli/pull/365), [mobilecli#389](https://github.com/mobile-next/mobilecli/pull/389))
* Perf: Cache Robot per device id ([#430](https://github.com/mobile-next/mobile-mcp/pull/430))
* Fix: Keep ref, selected, checked and enabled on screen elements ([#421](https://github.com/mobile-next/mobile-mcp/pull/421))
* Fix: Validate install path, coordinates and mobilecli JSON output ([#425](https://github.com/mobile-next/mobile-mcp/pull/425))
* Fix: Resolve mobilecli binary from scoped `@mobilenext` packages ([#419](https://github.com/mobile-next/mobile-mcp/pull/419))
* Chore: Correct destructive/readOnly tool annotation hints ([#408](https://github.com/mobile-next/mobile-mcp/pull/408))
* Docs: Translate README to Japanese and Simplified Chinese ([#426](https://github.com/mobile-next/mobile-mcp/pull/426))
* Chore: Upgrade bundled mobilecli from 1.0.0 to 1.0.9 ([#417](https://github.com/mobile-next/mobile-mcp/pull/417), [#428](https://github.com/mobile-next/mobile-mcp/pull/428))
* Feat: Per-platform npm packages, npm now downloads only the binary for the current platform ([mobilecli#134](https://github.com/mobile-next/mobilecli/pull/134))
* Feat: On-screen keyboard excluded from `dump ui` by default, use `full` boolean to include it ([mobilecli#398](https://github.com/mobile-next/mobilecli/pull/398))
* Fix(iOS): Don't fail device listing when one device is untrusted ([mobilecli#373](https://github.com/mobile-next/mobilecli/pull/373))
* Feat(Android): Device Kit agent is now embedded, no APK install required ([mobilecli#387](https://github.com/mobile-next/mobilecli/pull/387))
* Perf(Android): Faster screenshots and view tree snapshots via on-device agent ([mobilecli#368](https://github.com/mobile-next/mobilecli/pull/368))
## [1.0.2](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.2) (2026-08-09)
* Fix: Round coordinates before passing them to mobilecli ([#403](https://github.com/mobile-next/mobile-mcp/pull/403)), thanks to [@a1573595](https://github.com/a1573595)
* Fix(android): Recurse into mobilecli children when listing UI elements ([#406](https://github.com/mobile-next/mobile-mcp/pull/406))
## [1.0.1](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.1) (2026-08-06)
* Feat(cloud): Improve remote device MCP tools and add Mobile Next Cloud logi ([#398](https://github.com/mobile-next/mobile-mcp/pull/398))
## [1.0.0](https://github.com/mobile-next/mobile-mcp/releases/tag/1.0.0) (2026-08-02)
**BREAKING CHANGE**
Starting from version 1.0.0, mobilecli is used as the backend, instead of the old typescript code.
If you see any regression, please let us know immediately through a github issue (https://github.com/mobile-next/mobile-mcp/issues)
You can use environment variable `MOBILEMCP_LEGACY_ROBOT` to force old implementation. Legacy code will be removed 1 month from this notice.
* Feat: Route devices through mobilecli by default ([#396](https://github.com/mobile-next/mobile-mcp/pull/396))
## [0.0.62](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.62) (2026-07-11)
* iOS: Support "-" (hyphen) in iOS bundle identifier ([#377](https://github.com/mobile-next/mobile-mcp/pull/377)), thanks to [@TsurP](https://github.com/TsurP)
* Fix: Properly resolve symlinks for paths allowlist ([#377](https://github.com/mobile-next/mobile-mcp/pull/377)), thanks to [@TsurP](https://github.com/TsurP)
* Fix: Node v20 is required ([#375](https://github.com/mobile-next/mobile-mcp/pull/375))
* Android: Get screen density of Android devices ([#162](https://github.com/mobile-next/mobile-mcp/pull/162)), thanks to [@hiking93](https://github.com/hiking93)
* Docs: Revamp README and add ROADMAP.md ([#378](https://github.com/mobile-next/mobile-mcp/pull/378))
* Chore: Bump mobilewright to 0.0.48 ([#373](https://github.com/mobile-next/mobile-mcp/pull/373))
## [0.0.61](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.61) (2026-07-02)
* Fix: Catch system signals for clean v8 exit ([#366](https://github.com/mobile-next/mobile-mcp/pull/366))
* Fix: Detect go-ios installed via npm (bare semver version) ([#355](https://github.com/mobile-next/mobile-mcp/pull/355)), thanks to [@ravijagga](https://github.com/ravijagga)
* Docs: Added CONTRIBUTING.md ([#365](https://github.com/mobile-next/mobile-mcp/pull/365))
* Chore: Updated hono packages for security ([#367](https://github.com/mobile-next/mobile-mcp/pull/367))
## [0.0.60](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.60) (2026-06-15)
* Chore: Updated mobilewright SDK version ([#361](https://github.com/mobile-next/mobile-mcp/pull/361))
## [0.0.59](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.59) (2026-06-09)
* Chore: Updated hono packages for security ([#349](https://github.com/mobile-next/mobile-mcp/pull/349))
* Chore: Updated mobilewright SDK version ([#350](https://github.com/mobile-next/mobile-mcp/pull/350))
## [0.0.58](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.58) (2026-06-02)
* Fix: Understand getRobot device types and platforms ([#346](https://github.com/mobile-next/mobile-mcp/pull/346))
* Chore: Moved tests from mocha/nyc to playwright to reduce dependency vulnerabilities ([#347](https://github.com/mobile-next/mobile-mcp/pull/347))
## [0.0.57](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.57) (2026-05-28)
* Chore: Update mobilewright to 0.0.41 ([#341](https://github.com/mobile-next/mobile-mcp/pull/341))
## [0.0.56](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.56) (2026-05-17)
* Chore: Update mobilewright to 0.0.38 ([#338](https://github.com/mobile-next/mobile-mcp/pull/338))
* Fix: Restore mcp-publisher functionality ([#337](https://github.com/mobile-next/mobile-mcp/pull/337))
## [0.0.55](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.55) (2026-05-16)
* General: Replace mobilecli with mobilewright SDK ([#334](https://github.com/mobile-next/mobile-mcp/pull/334))
* General: Bump fast-xml-parser to 5.8.0 to fix security vulnerability ([#335](https://github.com/mobile-next/mobile-mcp/pull/335))
## [0.0.54](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54) (2026-05-04)
* Server: Update mobilecli to 0.3.70
* iOS: Fixed cases where testmanagerd would get Device Kit stuck in a black screen of death
* iOS: Added 'placeholder' to view tree response
## [0.0.53](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.53) (2026-05-01)
* Server: Add `mobile_list_crashes` tool to list crash reports on a device
* Server: Add `mobile_get_crash` tool to retrieve full crash report content
* Server: Upgrade mobilecli from 0.2.0 to 0.3.68
* iOS: Replaced use of WebdriverAgent with iOS Device Kit (open source, apache license)
* CI: Restrict `contents` permission to `read`
* CI: Remove Java setup step from build workflow
## [0.0.52](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.52) (2026-04-13)
* Server: Block cross-origin requests on SSE transport ([#311](https://github.com/mobile-next/mobile-mcp/pull/311))
* Server: Warn when SSE server starts without `MOBILEMCP_AUTH` set ([#311](https://github.com/mobile-next/mobile-mcp/pull/311))
* Server: Reject concurrent SSE connections instead of silently replacing them ([#311](https://github.com/mobile-next/mobile-mcp/pull/311))
* Server: Clear SSE transport on connection close to allow reconnection ([#311](https://github.com/mobile-next/mobile-mcp/pull/311))
* Server: Update mobilecli dependency from @mobilenext/mobilecli to mobilecli 0.2.0 ([#316](https://github.com/mobile-next/mobile-mcp/pull/316))
* CI: Fix script injection by passing `github.ref_name` through env vars ([#314](https://github.com/mobile-next/mobile-mcp/pull/314))
* CI: Use `npm ci` instead of `npm install` for reproducible builds ([#314](https://github.com/mobile-next/mobile-mcp/pull/314))
* CI: Pin mcp-publisher to version 1.5.0 ([#314](https://github.com/mobile-next/mobile-mcp/pull/314))
* CI: Remove `npm update` from tag release to preserve lockfile integrity ([#314](https://github.com/mobile-next/mobile-mcp/pull/314))
## [0.0.51](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51) (2026-04-03)
* Server: Replace `--port` with `--listen` flag accepting `[host:]port` format, default to localhost ([#306](https://github.com/mobile-next/mobile-mcp/pull/306))
* Server: Add optional Bearer token auth via `MOBILEMCP_AUTH` env variable ([#306](https://github.com/mobile-next/mobile-mcp/pull/306))
* Server: Add `MOBILEMCP_DISABLE_TELEMETRY` env variable to opt out of anonymous telemetry ([#305](https://github.com/mobile-next/mobile-mcp/pull/305))
* Server: Security update for path-to-regexp package ([#307](https://github.com/mobile-next/mobile-mcp/pull/307))
## [0.0.50](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.50) (2026-03-27)
* Server: Restrict open_url tool to http/https schemes unless `MOBILEMCP_ALLOW_UNSAFE_URLS=1` is set ([#299](https://github.com/mobile-next/mobile-mcp/pull/299)) thanks to [@manthanghasadiya](https://github.com/manthanghasadiya) for reporting this.
## [0.0.49](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49) (2026-03-24)
* Server: Fix path traversal in save screenshot and record video ([#296](https://github.com/mobile-next/mobile-mcp/pull/296)) thanks to [@AbhiTheModder](https://github.com/AbhiTheModder) for reporting this.
## [0.0.48](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.48) (2026-03-20)
* Server: Security updates for fast-xml-parser ([#292](https://github.com/mobile-next/mobile-mcp/pull/292))
* Server: Fix handling errors in getDeviceType to prevent empty device list ([#286](https://github.com/mobile-next/mobile-mcp/pull/286)) thanks to [@ls-andy](https://github.com/ls-andy)
## [0.0.47](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.47) (2026-03-09)
* Server: Use zod coerce to fix number parameter parsing ([#284](https://github.com/mobile-next/mobile-mcp/pull/284))
* Server: Updated packages for security ([#285](https://github.com/mobile-next/mobile-mcp/pull/285))
* iOS: Support locales when launching apps ([#283](https://github.com/mobile-next/mobile-mcp/pull/283))
* Android: Support locales when launching apps ([#283](https://github.com/mobile-next/mobile-mcp/pull/283))
## [0.0.46](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.46) (2026-03-03)
* Server: Improved tool description for listing devices, easier on prompting ([#282](https://github.com/mobile-next/mobile-mcp/pull/282))
* iOS: Added support for screen recording for both real devices and simulators ([#282](https://github.com/mobile-next/mobile-mcp/pull/282))
* Android: Added support for screen recording for both real devices and emulators ([#282](https://github.com/mobile-next/mobile-mcp/pull/282))
## [0.0.45](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.45) (2026-03-02)
* Server: Updated fast-xml-parser package for security ([#281](https://github.com/mobile-next/mobile-mcp/pull/281))
* Server: Fix noParams issue that started annoying Claude Code recently ([#280](https://github.com/mobile-next/mobile-mcp/pull/280))
* Android: Fix shell escaping through launchApp ([#279](https://github.com/mobile-next/mobile-mcp/pull/279)) thanks to [@yuhanghuang](https://github.com/yuhanghuang)
* Android: Escape url when calling openUrl ([#278](https://github.com/mobile-next/mobile-mcp/pull/278)) thanks to [yuhanghuang](https://github.com/yuhanghuang)
## [0.0.44](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.44) (2026-02-25)
* General: Rolling out support for remote devices, allocate Android and iOS devices on Mobile Fleet ([#273](https://github.com/mobile-next/mobile-mcp/pull/273))
## [0.0.43](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.43) (2026-02-24)
* General: Increase buffers used for screenshots, fixes bugs where screenshot was >4MB ([#270](https://github.com/mobile-next/mobile-mcp/pull/270))
* General: Upgraded several npm packages for security ([#272](https://github.com/mobile-next/mobile-mcp/pull/272))
## [0.0.42](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.42) (2026-02-03)
* General: Upgraded mobilecli to 0.0.54, [see changes](https://github.com/mobile-next/mobilecli/releases) ([ba3ec1b](https://github.com/mobile-next/mobile-mcp/commit/ba3ec1b9251487ad8444eb22fa3312c7b79d7787))
* General: Updated fast-xml-parser package for security ([#261](https://github.com/mobile-next/mobile-mcp/pull/261))
## [0.0.41](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.41) (2026-01-27)
* General: upgraded mobilecli to 0.0.52, [see changes](https://github.com/mobile-next/mobilecli/releases) ([d7e25f3](https://github.com/mobile-next/mobile-mcp/commit/d7e25f3543e87a436572c29f2b1766bd276a4d68))
* Android: fix: include elements with resource-id or checkable attributes ([#254](https://github.com/mobile-next/mobile-mcp/pull/254)) by [@singhsume123](https://github.com/singhsume123)
## [0.0.40](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.40) (2026-01-15)
* Server: bump @modelcontextprotocol/sdk from 1.24.2 to 1.25.2 for security ([#252](https://github.com/mobile-next/mobile-mcp/pull/252))
## [0.0.39](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.39) (2026-01-01)
* Server: added tool annotations for improved LLM tool understanding ([#246](https://github.com/mobile-next/mobile-mcp/pull/246))
* iOS: added 'duration' parameter to longpress for custom press durations ([#247](https://github.com/mobile-next/mobile-mcp/pull/247))
* Android: added 'duration' parameter to longpress for custom press durations ([#247](https://github.com/mobile-next/mobile-mcp/pull/247))
## [0.0.38](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.38) (2025-12-09)
* iOS: migrated iPhone Simulator calls to use mobilecli binary for improved performance ([#241](https://github.com/mobile-next/mobile-mcp/pull/241))
* iOS: automatically downloading and installing Webdriver Agent on simulator, get started in iOS development in seconds ([#241](https://github.com/mobile-next/mobile-mcp/pull/241))
## [0.0.37](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.37) (2025-12-08)
* Server: migrated to new mcp sdk tool registration API ([#239](https://github.com/mobile-next/mobile-mcp/pull/239))
* Server: updated to @modelcontextprotocol/sdk 1.24.2 and other dependencies for security ([#239](https://github.com/mobile-next/mobile-mcp/pull/239))
## [0.0.36](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.36) (2025-11-19)
* Server: upgraded libraries (glob, js-yaml) and mobilecli ([#234](https://github.com/mobile-next/mobile-mcp/pull/234))
## [0.0.35](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.35) (2025-11-14)
* Server: added list of available MCP tools to README for better discoverability ([043cf3d](https://github.com/mobile-next/mobile-mcp/commit/043cf3d))
* Android: fixed adb path resolution on Windows by always using .exe extension ([178b2fb](https://github.com/mobile-next/mobile-mcp/commit/178b2fb)) by [@mattheww-skyward](https://github.com/mattheww-skyward)
## [0.0.34](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.34) (2025-11-01)
* Server: dry-run release for benchmarking how mobilecli detects devices ([#226](https://github.com/mobile-next/mobile-mcp/pull/226))
## [0.0.33](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.33) (2025-10-20)
* Server: added debug information for understanding screenshot issues on old devices ([#213](https://github.com/mobile-next/mobile-mcp/pull/213))
## [0.0.32](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.32) (2025-10-08)
* Server: fixed wrong separator when listing iOS simulators ([#208](https://github.com/mobile-next/mobile-mcp/pull/208))
* iOS: double tap at screen location ([#207](https://github.com/mobile-next/mobile-mcp/pull/207))
* Android: reduce stdout pollution by adb shell monkey ([#211](https://github.com/mobile-next/mobile-mcp/pull/211))
* Android: fix mobile_take_screenshot on very old android devices ([#204](https://github.com/mobile-next/mobile-mcp/pull/204)) by [@boulaycote](https://github.com/boulaycote)
* Android: double tap at screen location ([#194](https://github.com/mobile-next/mobile-mcp/pull/194)) by [@SakshamSahgal](https://github.com/SakshamSahgal)
## [0.0.31](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.31) (2025-10-07)
* Server: resolve mobilecli libc issues on very old linux distros ([#206](https://github.com/mobile-next/mobile-mcp/pull/206))
* Server: identify mcp-client for compatiblity patches ([#205](https://github.com/mobile-next/mobile-mcp/pull/205))
## [0.0.30](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.30) (2025-10-06)
* Server: introduction of mobilecli tool, will replace imagemagick, sips, go-ios and adb in the future ([#196](https://github.com/mobile-next/mobile-mcp/pull/196))
* iOS: app installation and uninstallation ([#202](https://github.com/mobile-next/mobile-mcp/pull/202))
* Android: app installation and uninstallation ([#202](https://github.com/mobile-next/mobile-mcp/pull/202))
## [0.0.29](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.29) (2025-09-26)
* Server: bumped mcp sdk to latest version ([#199](https://github.com/mobile-next/mobile-mcp/pull/199))
* Server: locked production npm packages to specific version ([#199](https://github.com/mobile-next/mobile-mcp/pull/199))
* Server: renamed tool 'swipe_on_screen' to 'mobile_swipe_on_screen' ([#197](https://github.com/mobile-next/mobile-mcp/pull/197))
## [0.0.28](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.28) (2025-09-15)
* Server: added 'device' parameter to all tools ([#181](https://github.com/mobile-next/mobile-mcp/pull/181))
* Server: enable agents to access multiple devices at once (eg, 'explain what's on screen on all devices connected')
([#181](https://github.com/mobile-next/mobile-mcp/pull/181))
## [0.0.27](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.27) (2025-09-10)
* Server: use 'sips' image scaling on mac if found, removes requirement to install ImageMagick for image scaling ([#188](https://github.com/mobile-next/mobile-mcp/pull/188))
## [0.0.26](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.26) (2025-09-09)
* Server: support listing of mobile-mcp in github's mcp registry ([e96404e](https://github.com/mobile-next/mobile-mcp/commit/e96404e0e513e48ebcfe7956800203cc0f363526))
## [0.0.25](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.25) (2025-09-08)
* Server: install mobile-mcp in vscode with a single-click in README ([#173](https://github.com/mobile-next/mobile-mcp/pull/173))
* Android: try finding 'adb' under $HOME/Library/Android if $ANDROID_HOME is not defined ([#183](https://github.com/mobile-next/mobile-mcp/pull/183))
* Android: better escaping of text input, for improved security ([#182](https://github.com/mobile-next/mobile-mcp/pull/183))
## [0.0.24](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.24) (2025-08-24)
* iOS: new tool for long press ([#143](https://github.com/mobile-next/mobile-mcp/pull/143))
* Android: new tool for long press ([#143](https://github.com/mobile-next/mobile-mcp/pull/143))
* Android: fixed screenshot from devices with multiple devices (foldables) again ([#171](https://github.com/mobile-next/mobile-mcp/pull/171))
## [0.0.23](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.23) (2025-07-31)
* Android: fixed a bug where devices with multiple screens (such as foldables) failed to take and save screenshot ([#159](https://github.com/mobile-next/mobile-mcp/pull/159))
## [0.0.22](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.22) (2025-07-17)
* iOS: fixed detection of go-ios installation ([#132](https://github.com/mobile-next/mobile-mcp/pull/132) by [@codeaholicguy](https://github.com/codeaholicguy)
## [0.0.21](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.21) (2025-06-27)
* Server: use node: prefixed modules (like node:fs) ([449c498](https://github.com/mobile-next/mobile-mcp/commit/449c498e6e9a3e68aab55ea82f15c296171fc05e))
* iOS: automatically start WebDriverAgent on simulator if already installed ([#126](https://github.com/mobile-next/mobile-mcp/pull/126))
* Android: fixed detection of com.mobilenext.devicekit when running mcp on windows ([c11c642](https://github.com/mobile-next/mobile-mcp/commit/c11c6427c71cb7cef6ce87005047df977f6bea8a))
## [0.0.20](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.20) (2025-06-23)
* Server: new tool `save_screenshot` which saves the screenshot to disk, to be used by other mcp servers ([#112](https://github.com/mobile-next/mobile-mcp/pull/112))
* Server: new tool `use_default_device` which picks the only device that is connected, to speed up use ([#112](https://github.com/mobile-next/mobile-mcp/pull/112))
* iOS: Use wda to grab screenshots for both real devices and simulators ([#115](https://github.com/mobile-next/mobile-mcp/pull/115))
* Android: Support for utf-8 text in sendKeys, see [wiki page]() for getting started ([#117](https://github.com/mobile-next/mobile-mcp/pull/117))
## [0.0.19](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.19) (2025-06-16)
* Server: Fixed support for Windsurf, where some tools caused a -32602 error ([#101](https://github.com/mobile-next/mobile-mcp/pull/101)) by [@amebahead](https://github.com/amebahead)
* iOS: Support for swipe left and right. Support x,y,direction,duration for custom swipes ([#92](https://github.com/mobile-next/mobile-mcp/pull/92/)) by [@benlmyers](https://github.com/benlmyers)
* Android: Support for swipe left and right. Support x,y,direction,duration for custom swipes ([#92](https://github.com/mobile-next/mobile-mcp/pull/92/)) by [@benlmyers](https://github.com/benlmyers)
* Android: Fix for get elements on screen, where uiautomator prints out warnings before the actual xml ([#86](https://github.com/mobile-next/mobile-mcp/pull/86)) by [@wenerme](https://github.com/wenerme)
## [0.0.18](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.18) (2025-06-12)
* Server: New support for SSE (Server-Sent-Events) transport, [see wiki for more information](https://github.com/mobile-next/mobile-mcp/wiki/Using-SSE-Transport) ([1b70d40](https://github.com/mobile-next/mobile-mcp/commit/1b70d403cd562a97a0723464f2b286f2fd6eee0a))
* iOS: Using plutil for `simctl listapps` parsing, might probably fix some parsing issues ([cfba3aa](https://github.com/mobile-next/mobile-mcp/commit/cfba3aaac5beb66d08d1138fe42c924309ede303))
* Other: We have a new Slack server, join us at http://mobilenexthq.com/join-slack
## [0.0.17](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.17) (2025-05-16)
* iOS: Fixed parsing of simctl listapps where CFBundleDisplayName contains non-alphanumerical characters ([#59](https://github.com/mobile-next/mobile-mcp/issues/59)) ([bf19771d](https://github.com/mobile-next/mobile-mcp/pull/63/commits/bf19771dcd49444ba4841ec649e3a72a03b54c74))
## [0.0.16](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.16) (2025-05-10)
* Server: Detect if there is a new version of the mcp and notify user ([14b015f](https://github.com/mobile-next/mobile-mcp/commit/14b015f29ab47aa1f3ae122a670a58eb7ef51fd8))
* Server: Instead of returning x,y for tap, return [top,left,width,height] of elements on screen ([3169d2f](https://github.com/mobile-next/mobile-mcp/commit/3169d2f46f0c789e4c3188e137ac645d6f6eb27c))
* iOS: Fixed coordinates location for iOS with retina display after image scaledown ([3169d2f](https://github.com/mobile-next/mobile-mcp/commit/3169d2f46f0c789e4c3188e137ac645d6f6eb27c))
* iOS: Added detection of StaticText and Image in mobile_list_elements_on_screen ([debe75b](https://github.com/mobile-next/mobile-mcp/commit/debe75b5c8afcafcef8328201e9886bffdd1f128))
## [0.0.15](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.15) (2025-05-04)
* Android: Fixed broken Android screenshots on Windows because of crlf ([#53](https://github.com/mobile-next/mobile-mcp/pull/53/files) by [@hanyuan97](https://github.com/hanyuan97))
## [0.0.14](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.14) (2025-05-02)
* Server: Fix a bug where xcrun was required, now works on Linux as well ([7fddba7](https://github.com/mobile-next/mobile-mcp/commit/7fddba71af51690cfa76f81154f72c3120ab7f07))
* Server: Removed dependency on sharp which was causing issues during installation, now ImageMagick is an optional dependency
* Android: Try uiautomator-dump multiple times, in case ui hierarchy is not stable
* Android: Return more information about elements on screen for better element detection
* Android: Support for Android TV using dpad for navigation ([399443d](https://github.com/mobile-next/mobile-mcp/commit/399443d519284a54b670a1598689a73d178db2ec) by [@surajsau](https://github.com/surajsau))
## [0.0.13](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.13) (2025-04-17)
* Server: Fix a bug where 'adb' is required to even work with iOS-only ([#30](https://github.com/mobile-next/mobile-mcp/issues/30)) ([867f662](https://github.com/mobile-next/mobile-mcp/pull/35/commits/867f662ac2edc68d542519bd72d1762d3dbca18d))
* iOS: Support for orientation changes ([844dc0e](https://github.com/mobile-next/mobile-mcp/pull/28/commits/844dc0eb953169871b4cdd2a57735bf50abe721a))
* Android: Support for orientation changes (eg 'change device to landscape') ([844dc0e](https://github.com/mobile-next/mobile-mcp/pull/28/commits/844dc0eb953169871b4cdd2a57735bf50abe721a))
* Android: Improve element detection by using element name if label not found ([8e8aadf](https://github.com/mobile-next/mobile-mcp/pull/33/commits/8e8aadfd7f300ff5b7f0a7857a99d1103cd9e941) by [@tomoya0x00](https://github.com/tomoya0x00))
## [0.0.12](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.12) (2025-04-12)
* Server: If hitting an error with tunnel, forward proxy, wda, descriptive error and link to documentation will be returned
* iOS: go-ios path can be set in env GO_IOS_PATH
* iOS: Support go-ios that was built locally (no version)
* iOS: Return bundle display name for apps for better app launch
* iOS: Fixed finding element coordinates on retina displays
* iOS: Saving temporary screenshots onto temporary directory ([#19](https://github.com/mobile-next/mobile-mcp/issues/19))
* iOS: Find elements better by removing off-screen and hidden elements
* Android: Support for 'adb' under ANDROID_HOME
* Android: Find elements better using accessibility hints and class names
## [0.0.11](https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.11) (2025-04-06)
* Server: Support submit after sending text (\n)
* Server: Added support for multiple devices at the same time
* iOS: Support for iOS physical devices using go-ios ([see wiki](https://github.com/mobile-next/mobile-mcp/wiki/Getting-Started-with-iOS-Physical-Device))
* iOS: Added support for icons, search fields, and switches when getting elements on screen
---
## File: CODE_OF_CONDUCT.md
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
support@mobilenexthq.com.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.
---
## File: CONTRIBUTING.md
# Contributing to Mobile MCP
Thanks for your interest in contributing! This document covers the basics for getting set up and submitting changes.
## Code of Conduct
This project adheres to the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating, you agree to keep the community welcoming and respectful.
## Reporting bugs and requesting features
- Search [existing issues](https://github.com/mobile-next/mobile-mcp/issues) before opening a new one.
- Open one issue per bug or feature request.
- For bugs, include: mobile-mcp version, OS, target platform (iOS/Android), device/simulator/emulator, a minimal reproduction, and the actual vs. expected behavior.
- For larger feature proposals, please open an issue to discuss the design before sending a PR.
## Reporting security issues
Please **do not** file public GitHub issues for security vulnerabilities — see [SECURITY.md](SECURITY.md) for the private reporting process.
## Development setup
Requirements: Node.js 22+, and Xcode command line tools / Android Platform Tools if you plan to exercise a simulator, emulator, or real device.
```bash
git clone https://github.com/mobile-next/mobile-mcp.git
cd mobile-mcp
npm ci
npm run build
# lint
npm run lint
# tests (drives a real simulator/emulator/device via Playwright + c8 coverage)
npm test
```
`npm run watch` recompiles on change during development. A pre-commit hook (husky) runs `npm run lint` automatically.
## Submitting changes
- Branch off `main` and open a pull request when ready.
- Keep PRs focused — one concern per PR.
- Run `npm run build`, `npm run lint`, and `npm test` locally before pushing.
- CI (`.github/workflows/build.yml`) runs an npm audit, lint, and build on every PR — make sure it's green.
## License
By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).
---
## File: glama.json
{
"$schema": "https://glama.ai/mcp/schemas/server.json",
"maintainers": [
"gmegidish"
]
}
---
## File: llms-install.md
# Mobile MCP — Automated Installation Guide
This file is written for AI coding agents (Cline, Cursor, Claude Code, etc.) to install and
configure the Mobile MCP server automatically. Follow the steps in order.
## What this server does
Mobile MCP lets an agent drive real iOS and Android devices, simulators, and emulators through
one interface: taps, swipes, gestures, app install/launch/terminate, screenshots, structured UI
element extraction, screen recording, and crash reports.
## Prerequisites
Check that the user's machine has:
- **Node.js v20+** (the server runs via `npx`, no separate install needed)
- **Android** targets: Android Platform Tools with `adb` on `PATH`
- **iOS** targets (macOS only): Xcode command line tools
- At least one target available: a booted iOS Simulator, a running Android emulator, or a
connected real device
No API key or credentials are required.
## Installation
Add the server to the MCP configuration.
```json
{
"mcpServers": {
"mobile-mcp": {
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
```
## Verify the installation
Ask the agent to call the `mobile_list_available_devices` tool. A working install returns the list
of connected simulators, emulators, and devices. If the list is empty, make sure a simulator or
emulator is running, or that a device is connected and authorized.
## Notes
- **iOS real devices** need extra setup (go-ios + WebDriverAgent + a device tunnel). Simulators and
Android need no extra setup beyond the prerequisites above. See the
[README](https://github.com/mobile-next/mobile-mcp) and
[wiki](https://github.com/mobile-next/mobile-mcp/wiki) for details.
---
## File: manifest.json
{
"manifest_version": "0.3",
"name": "mobile-mcp",
"display_name": "Mobile MCP",
"version": "1.0.2",
"description": "Mobile automation for AI agents: control Android and iOS devices, emulators and simulators — launch apps, tap, swipe, type, take screenshots, read the accessibility tree.",
"author": {
"name": "Mobile Next",
"url": "https://mobilenext.ai"
},
"homepage": "https://mobilenext.ai/docs",
"license": "Apache-2.0",
"icon": "icon.png",
"keywords": ["mobile", "android", "ios", "automation", "testing"],
"compatibility": {
"platforms": ["darwin"]
},
"privacy_policies": ["https://mobilenext.ai/privacy"],
"server": {
"type": "node",
"entry_point": "lib/index.js",
"mcp_config": {
"command": "node",
"args": ["${__dirname}/lib/index.js"]
}
}
}
---
## File: mcp.json
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"mobile-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
}
}
---
## File: package.json
{
"name": "@mobilenext/mobile-mcp",
"mcpName": "io.github.mobile-next/mobile-mcp",
"version": "0.0.1",
"description": "Mobile MCP",
"repository": {
"type": "git",
"url": "git+https://github.com/mobile-next/mobile-mcp.git"
},
"engines": {
"node": ">=20"
},
"license": "Apache-2.0",
"scripts": {
"build": "tsc",
"start": "node lib/index.js",
"lint": "eslint .",
"fixlint": "eslint . --fix",
"test": "c8 playwright test",
"watch": "tsc --watch",
"clean": "rm -rf lib",
"prepare": "husky"
},
"files": [
"lib"
],
"dependencies": {
"@modelcontextprotocol/express": "2.0.0",
"@modelcontextprotocol/node": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"ajv": "^8.18.0",
"commander": "14.0.0",
"express": "5.1.0",
"fast-xml-parser": "5.8.0",
"mobilewright": "0.0.67",
"qs": "^6.15.0",
"zod": "^4.2.0",
"zod-to-json-schema": "3.25.0"
},
"devDependencies": {
"@eslint/eslintrc": "^3.2.0",
"@eslint/js": "^9.19.0",
"@modelcontextprotocol/client": "^2.3.1",
"@playwright/test": "^1.49.0",
"@stylistic/eslint-plugin": "^3.0.1",
"@types/commander": "^2.12.0",
"@types/express": "^5.0.3",
"@types/node": "^22.13.10",
"@typescript-eslint/eslint-plugin": "^8.28.0",
"@typescript-eslint/parser": "^8.26.1",
"@typescript-eslint/utils": "^8.26.1",
"c8": "^10.1.3",
"eslint": "^9.19.0",
"eslint-plugin": "^1.0.1",
"eslint-plugin-import": "^2.31.0",
"eslint-plugin-notice": "^1.0.0",
"husky": "^9.1.7",
"typescript": "5.8.2"
},
"main": "index.js",
"bin": {
"mcp-server-mobile": "lib/index.js"
},
"directories": {
"lib": "lib"
},
"author": "",
"bugs": {
"url": "https://github.com/mobile-next/mobile-mcp/issues"
},
"homepage": "https://github.com/mobile-next/mobile-mcp#readme"
}
---
## File: plugin.json
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "mobile-mcp",
"description": "Mobile automation for AI agents: control Android and iOS devices, emulators and simulators — launch apps, tap, swipe, type, take screenshots, read the accessibility tree.",
"author": {
"name": "Mobile Next",
"url": "https://mobilenext.ai"
},
"homepage": "https://mobilenext.ai/docs",
"repository": "https://github.com/mobile-next/mobile-mcp",
"license": "Apache-2.0",
"keywords": ["mobile", "android", "ios", "automation", "testing", "mcp"]
}
---
## File: ROADMAP.md
# Roadmap
This is a living document of planned and in-progress features. Items are roughly prioritized top-to-bottom. Have a feature request? [Open an issue](https://github.com/mobile-next/mobile-mcp/issues/new/choose).
| Feature | Description | Status |
|---|---|---|
| **File system tools** | List, push, and pull files on the device or within an app container. | Planned |
| **App launch options** | Launch an app with custom arguments. | Planned |
| **Pinch to zoom** | Pinch-in and pinch-out gesture support for zooming in and out. | Planned |
| **WebView support** | Inspect and interact with WebView content inside native apps. | Planned |
| **Flutter UI support** | Dump Flutter widget trees with semantics and element types, so agents see Flutter apps like native ones. | Planned |
| **Browser support** | Drive the on-device browser, Safari on iOS and Chrome on Android, alongside native apps. | Planned |
| **Device settings** | Toggle dark mode, override the timezone, and switch wifi and airplane mode to test offline behaviour. | Planned |
| **Clear app storage** | Clear an app's cache and documents between runs. | Planned |
## Done Done
Shipped in 2026, most recent first.
| Feature | Description | Date |
|---|---|---|
| **Streamable HTTP support** | `--listen` serves MCP Streamable HTTP on `/mcp` (stateless). Replaces deprecated SSE on `/mcp`. | 2026-09-11 |
| **Device logs** | Read device system logs — syslog, console, and logcat. | 2026-09-08 |
| **Background daemon for speedup** | A long-lived background process that keeps device connections, agents and tunnels warm between tool calls, so each call skips discovery and setup and returns in milliseconds instead of seconds. | 2026-09-08 |
| **Element refs in UI dump** | Every element in the UI dump gets a stable `@ref` id that can be passed to tap, type, etc., so agents act on elements without coordinates. | 2026-09-08 |
| **Embed Android Device Kit in the binary** | Ship the Android agent as a dex embedded in the executable and run it via `app_process`, so nothing gets installed on the device and the Device Kit APK goes away. | 2026-09-08 |
| **Better screenshot handling** | Native cropping and scaling, removing the dependency on `sips` and ImageMagick. | 2026-09-08 |
| **iOS on Device Kit** | Replaced WebDriverAgent with our own Device Kit on real iOS devices too. | 2026-09-04 |
| **Remove go-ios dependency** | Dropped the external `go-ios` dependency entirely. | 2026-09-04 |
| **iOS Device Kit on Simulator** | Replaced WebDriverAgent with our own Device Kit for iOS Simulator automation. | 2026-05-01 |
| **List crashes** | Retrieve crash reports from the device. | 2026-05-01 |
| **SSE authentication** | Optional Bearer-token auth for the SSE server (`--listen` + `MOBILEMCP_AUTH`). | 2026-04-03 |
| **Safe URL schemes** | Restrict `open url` to safe schemes unless explicitly enabled. | 2026-03-27 |
| **Screen recording** | Record the device screen to an mp4 file. | 2026-03-03 |
| **App launch locales** | Launch apps with a specific locale. | 2026-03-03 |
| **Long-press duration** | Control the duration of a long-press. | 2026-01-01 |
---
## File: SECURITY.md
# Security Policy
## Supported Versions
All versions of this project are currently being supported with security updates.
| Version | Supported |
| ------- | ------------------ |
| All | :white_check_mark: |
## Important notes regarding use of mobile-mcp
**mobile-mcp** is an MCP server for controlling a mobile device. Device may be a real iOS device, real Android device, an iOS Simulator or Android
Emulator.
You may use mobile-mcp for various tasks, such as app development, marketing automation, quality assurance and so on.
As a rule of thumb, verify which tools your Agent is invoking. It has access to the device or simulator, it may operate the device to the security
scope of that device. It is suggested that you use a device that is purposed for this use.
## Reporting a Vulnerability
To report a security vulnerability, please join our Slack channel at http://mobilenexthq.com/join-slack and DM the moderators with details of the vulnerability.
We take all security reports seriously and will respond as quickly as possible.
---
## File: server.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",
"repository": {
"url": "https://github.com/mobile-next/mobile-mcp",
"source": "github"
},
"version": "{{VERSION}}",
"packages": [
{
"registryType": "npm",
"registryBaseUrl": "https://registry.npmjs.org",
"identifier": "@mobilenext/mobile-mcp",
"version": "{{VERSION}}",
"transport": {
"type": "stdio"
}
}
]
}
---
## File: smithery.yaml
startCommand:
type: stdio
configSchema:
type: object
required: []
properties: {}
commandFunction: |-
() => ({ command: 'npx', args: ['-y', '@mobilenext/mobile-mcp@latest'] })
---
## File: tsconfig.json
{
"compilerOptions": {
"target": "ESNext",
"skipLibCheck": true,
"esModuleInterop": true,
"moduleResolution": "node",
"strict": true,
"module": "CommonJS",
"outDir": "./lib"
},
"include": [
"src",
],
}
---
## File: .c8rc.json
{
"include": ["lib/**/*.js"],
"exclude": ["node_modules/**", "lib/**/*.js.map"],
"reporter": ["html", "text"],
"temp-directory": "./coverage/tmp"
}
---
## File: .mocharc.yml
timeout: 60s
---
## File: plugin/hooks/hooks.json
{ "modules": ["./register.tsx"] }
---
## File: plugin/.claude-plugin/plugin.json
{
"name": "mobile-mcp",
"version": "1.0.7",
"description": "Mobile automation for Claude Code: the mobile-mcp server, and /mobile-mirror, a live, clickable device screen in a pane.",
"author": {
"name": "Mobile Next",
"url": "https://mobilenext.ai"
},
"homepage": "https://mobilenext.ai/docs",
"repository": "https://github.com/mobile-next/mobile-mcp",
"license": "Apache-2.0",
"keywords": ["mobile", "android", "ios", "automation", "testing", "mcp", "mirror"],
"mcpServers": {
"mobile-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@mobilenext/mobile-mcp@latest"]
}
},
"types": "./types/index.d.ts"
}
---
## File: skills/mobile-automation/SKILL.md
---
name: mobile-automation
metadata:
openclaw:
requires:
bins:
- npx
---
# Mobile Automation with Mobile MCP
Tools for driving real phones, emulators and simulators. All tools are
prefixed `mobile_`.
## Workflow
1. **Pick a device.** Call `mobile_list_available_devices` and use one of the
returned devices for every subsequent call. If no device is available, ask
the user to connect one (Android: `adb devices` must show it; iOS:
simulator booted or device paired).
2. **See the screen.** Prefer `mobile_list_elements_on_screen` — it returns
the accessibility tree with element labels and coordinates. It is faster,
cheaper, and more reliable than screenshots. Fall back to
`mobile_take_screenshot` only when elements are missing or you need visual
confirmation (games, canvas-drawn UI, image content).
3. **Act.** `mobile_click_on_screen_at_coordinates`, `mobile_swipe_on_screen`,
`mobile_type_keys`, `mobile_press_button` (HOME, BACK, VOLUME, ENTER),
`mobile_launch_app` / `mobile_terminate_app` / `mobile_list_apps`,
`mobile_open_url`.
4. **Verify after every action.** Re-list elements (or re-screenshot) to
confirm the UI changed as expected before the next step. Mobile UIs
animate; if the expected element is not there yet, wait briefly and check
again rather than tapping blind.
## Tips
- Click the **center** of an element's bounds, not its top-left corner.
- To type, first tap the input field, confirm it is focused, then
`mobile_type_keys`.
- Use `mobile_save_screenshot` when the user wants the image as a file;
`mobile_start_screen_recording` / `mobile_stop_screen_recording` for videos.
- App crashed? `mobile_list_crashes` and `mobile_get_crash` fetch crash logs.
- Screen size from `mobile_get_screen_size`; coordinates are in that space.
- Real devices in the cloud (no local hardware): `mobile_login_to_cloud_provider`,
then `mobile_list_remote_devices` / `mobile_allocate_remote_device`, and
release with `mobile_release_remote_device` when done. See
https://mobilenext.ai/docs for details.