@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.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
- This is a [Model Context Protocol (MCP) server](https://github.com/modelcontextprotocol) 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).
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 | ✅ | go-ios + WebDriverAgent + tunnel |
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
- ### SSE Server Mode
382
+ ### ☁️ Scale up, use a cloud device
370
383
 
371
- By default, Mobile MCP runs over stdio. To start an SSE server instead, use the `--listen` flag:
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 SSE server, set the `MOBILEMCP_AUTH` environment variable:
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 SSE server — every request must then send `Authorization: Bearer <token>`. | `MOBILEMCP_AUTH=my-secret-token` |
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)** — run all of it against real iOS and Android devices in the cloud, on demand.
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.