@mobilenext/mobile-mcp 1.0.1 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ja.md +572 -0
- package/README.md +38 -11
- package/README.zh-CN.md +572 -0
- package/lib/format-elements.js +82 -0
- package/lib/mobile-device.js +106 -19
- package/lib/mobilecli.js +18 -14
- package/lib/server.js +219 -86
- package/package.json +2 -2
- package/lib/image-utils.js +0 -155
package/README.md
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
# Mobile Next - MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
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).
|
|
6
|
+
|
|
4
7
|
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.
|
|
5
8
|
|
|
6
9
|
**Works with Claude Code, Codex, Gemini, GitHub Copilot, Antigravity** — or any MCP-compatible client.
|
|
7
10
|
|
|
11
|
+
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.
|
|
12
|
+
|
|
8
13
|
<h4 align="center">
|
|
9
14
|
<a href="https://github.com/mobile-next/mobile-mcp">
|
|
10
15
|
<img src="https://img.shields.io/github/stars/mobile-next/mobile-mcp" alt="Mobile Next Stars" />
|
|
@@ -21,7 +26,7 @@ This server allows Agents and LLMs to interact with native iOS/Android applicati
|
|
|
21
26
|
<a href="https://github.com/mobile-next/mobile-mcp/wiki">
|
|
22
27
|
<img src="https://img.shields.io/badge/documentation-wiki-blue" alt="wiki" />
|
|
23
28
|
</a>
|
|
24
|
-
<a href="https://mobilenext.ai/join-slack">
|
|
29
|
+
<a href="https://mobilenext.ai/join-slack?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=badge">
|
|
25
30
|
<img src="https://img.shields.io/badge/join-Slack-blueviolet?logo=slack&style=flat" alt="join on Slack" />
|
|
26
31
|
</a>
|
|
27
32
|
</h4>
|
|
@@ -59,7 +64,7 @@ How we help to scale mobile automation:
|
|
|
59
64
|
| Target | Supported | Setup |
|
|
60
65
|
|---|:---:|---|
|
|
61
66
|
| iOS Simulator | ✅ | Xcode + a booted simulator (`xcrun simctl`) |
|
|
62
|
-
| iOS Real Device | ✅ |
|
|
67
|
+
| iOS Real Device | ✅ | Device connected over USB and trusted |
|
|
63
68
|
| Android Emulator | ✅ | Android SDK + running emulator (`adb`) |
|
|
64
69
|
| Android Real Device | ✅ | `adb` + USB debugging enabled & authorized |
|
|
65
70
|
|
|
@@ -70,9 +75,18 @@ How we help to scale mobile automation:
|
|
|
70
75
|
- **`mobile_get_screen_size`** - Get the screen size of the mobile device in pixels
|
|
71
76
|
- **`mobile_get_orientation`** - Get the current screen orientation of the device
|
|
72
77
|
- **`mobile_set_orientation`** - Change the screen orientation (portrait/landscape)
|
|
78
|
+
- **`mobile_set_location`** - Override the GPS location reported by the device, or clear the override
|
|
79
|
+
- **`mobile_clipboard`** - Read or replace the device clipboard
|
|
80
|
+
|
|
81
|
+
### Remote Devices (Mobile Next Cloud)
|
|
82
|
+
- **`mobile_login_to_cloud_provider`** - Authenticate this machine with the cloud device provider (browser-based device-code login)
|
|
83
|
+
- **`mobile_list_remote_devices`** - List device models available to reserve from the cloud fleet
|
|
84
|
+
- **`mobile_allocate_remote_device`** - Reserve a physical cloud device for exclusive use
|
|
85
|
+
- **`mobile_release_remote_device`** - Release a reserved cloud device back to the fleet
|
|
73
86
|
|
|
74
87
|
### App Management
|
|
75
88
|
- **`mobile_list_apps`** - List all installed apps on the device
|
|
89
|
+
- **`mobile_get_foreground_app`** - Get the app currently in the foreground
|
|
76
90
|
- **`mobile_launch_app`** - Launch an app using its package name
|
|
77
91
|
- **`mobile_terminate_app`** - Stop and terminate a running app
|
|
78
92
|
- **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
|
|
@@ -94,9 +108,11 @@ How we help to scale mobile automation:
|
|
|
94
108
|
- **`mobile_press_button`** - Press device buttons (HOME, BACK, VOLUME_UP/DOWN, ENTER, etc.)
|
|
95
109
|
- **`mobile_open_url`** - Open URLs in the device browser
|
|
96
110
|
|
|
97
|
-
### Crash Reports
|
|
111
|
+
### Logs & Crash Reports
|
|
112
|
+
- **`mobile_get_device_logs`** - Collect live device logs (logcat on Android, unified log on iOS), optionally saved to a file
|
|
98
113
|
- **`mobile_list_crashes`** - List crash reports available on the device
|
|
99
114
|
- **`mobile_get_crash`** - Get the full content of a crash report by its ID
|
|
115
|
+
- **`mobile_batch_commands`** - Run multiple tools in sequence in a single call (e.g. click, type, click), optionally listing screen elements at the end
|
|
100
116
|
|
|
101
117
|
## 🏗️ Mobile MCP Architecture
|
|
102
118
|
|
|
@@ -121,9 +137,6 @@ What you will need to connect MCP with your agent and mobile devices:
|
|
|
121
137
|
- [node.js](https://nodejs.org/en/download/) v20+
|
|
122
138
|
- [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/)
|
|
123
139
|
|
|
124
|
-
For iOS **real devices** (simulators and Android don't need these), you'll also need [go-ios](https://github.com/danielpaulus/go-ios), [WebDriverAgent](https://github.com/appium/WebDriverAgent) installed on the device, and an iOS device tunnel. See the [wiki](https://github.com/mobile-next/mobile-mcp/wiki) for setup.
|
|
125
|
-
|
|
126
|
-
|
|
127
140
|
## Installation and configuration
|
|
128
141
|
|
|
129
142
|
**Standard config** works in most of the tools:
|
|
@@ -366,6 +379,15 @@ Once the server is configured, ask your agent to list devices:
|
|
|
366
379
|
|
|
367
380
|
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).
|
|
368
381
|
|
|
382
|
+
### ☁️ Scale up, use a cloud device
|
|
383
|
+
|
|
384
|
+
Want to scale to hundreds of devices? Use Mobile MCP in your CI/CD pipeline?
|
|
385
|
+
|
|
386
|
+
In your Agent, prompt:
|
|
387
|
+
```text
|
|
388
|
+
log in to mobile next cloud and then show me which remote devices are available to me
|
|
389
|
+
```
|
|
390
|
+
|
|
369
391
|
### SSE Server Mode
|
|
370
392
|
|
|
371
393
|
By default, Mobile MCP runs over stdio. To start an SSE server instead, use the `--listen` flag:
|
|
@@ -392,7 +414,7 @@ MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
|
|
|
392
414
|
|
|
393
415
|
When set, all requests must include the header `Authorization: Bearer my-secret-token`.
|
|
394
416
|
|
|
395
|
-
### 🛠️ How to Use
|
|
417
|
+
### 🛠️ How to Use
|
|
396
418
|
|
|
397
419
|
After adding the MCP server to your IDE/Client, you can instruct your AI assistant to use the available tools.
|
|
398
420
|
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.
|
|
@@ -456,7 +478,6 @@ Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
|
|
|
456
478
|
10AM with a duration of 1 hour, copy the invitation link, and send it via
|
|
457
479
|
Gmail to contacts "team@example.com".
|
|
458
480
|
```
|
|
459
|
-
[More prompt examples can be found here.](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)
|
|
460
481
|
|
|
461
482
|
## Running & configuration
|
|
462
483
|
|
|
@@ -520,7 +541,7 @@ Mobile MCP is one piece of a toolkit for driving real mobile devices:
|
|
|
520
541
|
|
|
521
542
|
- **[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.
|
|
522
543
|
- **[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.
|
|
523
|
-
- **[Mobile Next Cloud](https://mobilenext.ai)** —
|
|
544
|
+
- **[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.
|
|
524
545
|
|
|
525
546
|
## 🚀 Roadmap
|
|
526
547
|
|
|
@@ -533,7 +554,7 @@ Contributions are welcome — code, docs, bug reports, and ideas.
|
|
|
533
554
|
- ⭐ **[Star the repo](https://github.com/mobile-next/mobile-mcp)** — the easiest way to help others discover Mobile MCP.
|
|
534
555
|
- Read [CONTRIBUTING.md](CONTRIBUTING.md) for how to build, test, and open a pull request.
|
|
535
556
|
- Browse [open issues](https://github.com/mobile-next/mobile-mcp/issues) to find something to work on.
|
|
536
|
-
- Questions and ideas are also welcome in our [Slack community](https://mobilenext.ai/join-slack).
|
|
557
|
+
- 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).
|
|
537
558
|
|
|
538
559
|
Please also review our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
539
560
|
|
|
@@ -544,3 +565,9 @@ Please also review our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
|
544
565
|
<a href = "https://github.com/mobile-next/mobile-mcp/graphs/contributors">
|
|
545
566
|
<img src = "https://contrib.rocks/image?repo=mobile-next/mobile-mcp"/>
|
|
546
567
|
</a>
|
|
568
|
+
|
|
569
|
+
## Privacy Policy
|
|
570
|
+
|
|
571
|
+
Mobile MCP runs locally and communicates only with the devices you connect.
|
|
572
|
+
See the Mobile Next privacy policy at https://mobilenext.ai/privacy for data
|
|
573
|
+
collection, usage, retention, and contact information.
|