@mobilenext/mobile-mcp 1.0.2 → 1.0.4
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 +577 -0
- package/README.md +49 -18
- package/README.zh-CN.md +577 -0
- package/lib/coordinate-mapping.js +27 -0
- package/lib/format-elements.js +82 -0
- package/lib/index.js +65 -39
- package/lib/jpeg.js +41 -0
- package/lib/mobile-device.js +85 -6
- package/lib/mobilecli.js +18 -14
- package/lib/server.js +247 -91
- package/package.json +4 -3
- 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,9 +379,18 @@ 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
|
|
|
369
|
-
###
|
|
382
|
+
### ☁️ Scale up, use a cloud device
|
|
370
383
|
|
|
371
|
-
|
|
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
|
+
|
|
391
|
+
### Streamable HTTP Server Mode
|
|
392
|
+
|
|
393
|
+
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:
|
|
372
394
|
|
|
373
395
|
```bash
|
|
374
396
|
npx @mobilenext/mobile-mcp@latest --listen 3000
|
|
@@ -380,19 +402,23 @@ This binds to `localhost:3000`. To bind to a specific interface:
|
|
|
380
402
|
npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000
|
|
381
403
|
```
|
|
382
404
|
|
|
383
|
-
Then configure your MCP client to connect to `http://<host>:3000/mcp
|
|
405
|
+
Then configure your MCP client to connect to `http://<host>: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.
|
|
406
|
+
|
|
407
|
+
> **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.
|
|
408
|
+
|
|
409
|
+
When binding to localhost, Host-header DNS rebinding protection is enabled automatically.
|
|
384
410
|
|
|
385
411
|
#### Authorization
|
|
386
412
|
|
|
387
|
-
To require Bearer token authorization on the
|
|
413
|
+
To require Bearer token authorization on the HTTP server, set the `MOBILEMCP_AUTH` environment variable:
|
|
388
414
|
|
|
389
415
|
```bash
|
|
390
416
|
MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
|
|
391
417
|
```
|
|
392
418
|
|
|
393
|
-
When set, all requests must include the header `Authorization: Bearer my-secret-token`.
|
|
419
|
+
When set, all requests must include the header `Authorization: Bearer my-secret-token`. When unset, the server accepts unauthenticated connections and logs a warning.
|
|
394
420
|
|
|
395
|
-
### 🛠️ How to Use
|
|
421
|
+
### 🛠️ How to Use
|
|
396
422
|
|
|
397
423
|
After adding the MCP server to your IDE/Client, you can instruct your AI assistant to use the available tools.
|
|
398
424
|
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 +482,6 @@ Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
|
|
|
456
482
|
10AM with a duration of 1 hour, copy the invitation link, and send it via
|
|
457
483
|
Gmail to contacts "team@example.com".
|
|
458
484
|
```
|
|
459
|
-
[More prompt examples can be found here.](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)
|
|
460
485
|
|
|
461
486
|
## Running & configuration
|
|
462
487
|
|
|
@@ -464,7 +489,7 @@ Gmail to contacts "team@example.com".
|
|
|
464
489
|
|
|
465
490
|
| Variable | Description | Example |
|
|
466
491
|
|---|---|---|
|
|
467
|
-
| `MOBILEMCP_AUTH` | Require a Bearer token on the
|
|
492
|
+
| `MOBILEMCP_AUTH` | Require a Bearer token on the Streamable HTTP server (`--listen`) — every request must then send `Authorization: Bearer <token>`. | `MOBILEMCP_AUTH=my-secret-token` |
|
|
468
493
|
| `MOBILEMCP_DISABLE_TELEMETRY` | Disable anonymous usage telemetry. | `MOBILEMCP_DISABLE_TELEMETRY=1` |
|
|
469
494
|
| `MOBILEMCP_ALLOW_UNSAFE_URLS` | Allow `mobile_open_url` to open non-standard URL schemes (blocked by default). | `MOBILEMCP_ALLOW_UNSAFE_URLS=1` |
|
|
470
495
|
| `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` |
|
|
@@ -480,7 +505,7 @@ Make sure you have your mobile platform SDKs (Xcode, Android SDK) installed and
|
|
|
480
505
|
|
|
481
506
|
### Telemetry
|
|
482
507
|
|
|
483
|
-
Mobile MCP collects anonymous usage telemetry via PostHog. To disable it, set the `MOBILEMCP_DISABLE_TELEMETRY` environment variable:
|
|
508
|
+
Mobile MCP collects anonymous usage telemetry via PostHog and Scarf. To disable it, set the `MOBILEMCP_DISABLE_TELEMETRY` environment variable:
|
|
484
509
|
|
|
485
510
|
```bash
|
|
486
511
|
MOBILEMCP_DISABLE_TELEMETRY=1 npx @mobilenext/mobile-mcp@latest
|
|
@@ -520,7 +545,7 @@ Mobile MCP is one piece of a toolkit for driving real mobile devices:
|
|
|
520
545
|
|
|
521
546
|
- **[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
547
|
- **[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)** —
|
|
548
|
+
- **[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
549
|
|
|
525
550
|
## 🚀 Roadmap
|
|
526
551
|
|
|
@@ -533,7 +558,7 @@ Contributions are welcome — code, docs, bug reports, and ideas.
|
|
|
533
558
|
- ⭐ **[Star the repo](https://github.com/mobile-next/mobile-mcp)** — the easiest way to help others discover Mobile MCP.
|
|
534
559
|
- Read [CONTRIBUTING.md](CONTRIBUTING.md) for how to build, test, and open a pull request.
|
|
535
560
|
- 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).
|
|
561
|
+
- 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
562
|
|
|
538
563
|
Please also review our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
539
564
|
|
|
@@ -544,3 +569,9 @@ Please also review our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
|
544
569
|
<a href = "https://github.com/mobile-next/mobile-mcp/graphs/contributors">
|
|
545
570
|
<img src = "https://contrib.rocks/image?repo=mobile-next/mobile-mcp"/>
|
|
546
571
|
</a>
|
|
572
|
+
|
|
573
|
+
## Privacy Policy
|
|
574
|
+
|
|
575
|
+
Mobile MCP runs locally and communicates only with the devices you connect.
|
|
576
|
+
See the Mobile Next privacy policy at https://mobilenext.ai/privacy for data
|
|
577
|
+
collection, usage, retention, and contact information.
|