Skip to content
Back to search

mobile-mcp

Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mobile-next/mobile-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mobile-next/mobile-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mobile-next--mobile-mcp/badge.svg)](/listings/mobile-next--mobile-mcp)

HTML

<a href="/listings/mobile-next--mobile-mcp"><img src="/api/listings/mobile-next--mobile-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Standard config** works in most of the tools:

{
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
    }
  }
}

<details> <summary>Amp</summary>

Add via the Amp VS Code extension settings screen or by updating your `settings.json` file:

"amp.mcpServers": {
  "mobile-mcp": {
    "command": "npx",
    "args": [
      "@mobilenext/mobile-mcp@latest"
    ]
  }
}

**Amp CLI:**

Run the following command in your terminal:

amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest

</details>

<details> <summary>Antigravity 2</summary>

Antigravity doesn't have a CLI command to add MCP servers, so add it manually. Edit `~/.gemini/config/mcp_config.json` and add:

{
  "mcpServers": {
    "mobile-mcp": {
      "command": "npx",
      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
    }
  }
}

</details>

<details> <summary>Cline</summary>

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)

</details>

<details> <summary>Claude Code</summary>

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:

claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest

</details>

<details> <summary>Claude Desktop</summary>

Follow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user), use json configuration above.

</details>

<details> <summary>Codex</summary>

Use the Codex CLI to add the Mobile MCP server:

codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"

Alternatively, create or edit the configuration file `~/.codex/config.toml` and add:

[mcp_servers.mobile-mcp]
command = "npx"
args = ["@mobilenext/mobile-mcp@latest"]

For more information, see the Codex MCP documentation.

</details>

<details> <summary>Copilot</summary>

Use the Copilot CLI to interactively add the Mobile MCP server:

/mcp add

You can edit the configuration file `~/.copilot/mcp-config.json` and add:

{
  "mcpServers": {
    "mobile-mcp": {
      "type": "local",
      "command": "npx",
      "tools": [
        "*"
      ],
      "args": [
        "@mobilenext/mobile-mcp@latest"
      ]
    }
  }
}

For more information, see the Copilot CLI documentation.

</details>

<details> <summary>Cursor</summary>

Click the button to install:

[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](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`.

</details>

<details> <summary>Gemini CLI</summary>

Use the Gemini CLI to add the Mobile MCP server:

gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest

</details>

<details> <summary>Goose</summary>

Click the button to install:

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".

</details>

<details> <summary>Kiro</summary>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "mobile-mcp",
  3. "description": "Mobile automation for AI agents on Android and iOS",
  4. "owner": {
  5. "name": "Mobile Next",
  6. "url": "https://mobilenext.ai"
  7. },
  8. "plugins": [
  9. {
  10. "name": "mobile-mcp",
  11. "source": "./plugin"
  12. }
  13. ]
  14. }
README.md · README · 633 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Mobile Next - MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices
  2. **English** | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
  3. 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).
  4. 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. **Works with Claude Code, Codex, Gemini, GitHub Copilot, Antigravity** — or any MCP-compatible client.
  6. 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.
  7. <h4 align="center">
  8. <a href="https://github.com/mobile-next/mobile-mcp">
  9. <img src="https://img.shields.io/github/stars/mobile-next/mobile-mcp" alt="Mobile Next Stars" />
  10. </a>
  11. <a href="https://www.npmjs.com/package/@mobilenext/mobile-mcp">
  12. <img src="https://img.shields.io/npm/dm/@mobilenext/mobile-mcp?logo=npm&style=flat&color=red" alt="npm" />
  13. </a>
  14. <a href="https://github.com/mobile-next/mobile-mcp/releases">
  15. <img src="https://img.shields.io/github/release/mobile-next/mobile-mcp" />
  16. </a>
  17. <a href="https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22mobile-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mobilenext%2Fmobile-mcp%40latest%22%5D%7D">
  18. <img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code" />
  19. </a>
  20. <a href="https://github.com/mobile-next/mobile-mcp/wiki">
  21. <img src="https://img.shields.io/badge/documentation-wiki-blue" alt="wiki" />
  22. </a>
  23. <a href="https://mobilenext.ai/join-slack?utm_source=github&utm_medium=readme&utm_campaign=mobile-mcp&utm_content=badge">
  24. <img src="https://img.shields.io/badge/join-Slack-blueviolet?logo=slack&style=flat" alt="join on Slack" />
  25. </a>
  26. </h4>
  27. <p align="center">
  28. <a href="https://www.star-history.com/?repos=mobile-next%2Fmobile-mcp">
  29. <picture>
  30. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=mobile-next/mobile-mcp&type=trending&theme=dark" />
  31. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=mobile-next/mobile-mcp&type=trending" />
  32. <img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=mobile-next/mobile-mcp&type=trending" />
  33. </picture>
  34. </a>
  35. </p>
  36. https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
  37. ## 🚀 Quick start
  38. **Quick install** detects the MCP clients on this machine (Claude Code, Codex, Cursor, VS Code, Gemini CLI and more) and lets you pick which ones to configure:
  39. ```bash
  40. npx @mobilenext/mobile-mcp@latest install
  41. ```
  42. Add `--yes` to configure every detected client without asking.
  43. Manual setup per client: [Installation and configuration](#installation-and-configuration)
  44. <p align="center">
  45. <a href="https://github.com/mobile-next/">
  46. <img alt="mobile-mcp" src="https://raw.githubusercontent.com/mobile-next/mobile-next-assets/refs/heads/main/mobile-mcp-banner.png" width="600" />
  47. </a>
  48. </p>
  49. ### Main use cases
  50. How we help to scale mobile automation:
  51. - 📲 Native app automation (iOS and Android) for testing or data-entry scenarios.
  52. - 📝 Scripted flows and form interactions without manually controlling simulators/emulators or real devices (iPhone, Samsung, Google Pixel etc)
  53. - 🧭 Automating multi-step user journeys driven by an LLM
  54. - 👆 General-purpose mobile application interaction for agent-based frameworks
  55. - 🤖 Enables agent-to-agent communication for mobile automation usecases, data extraction
  56. ## Main Features
  57. - 🚀 **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.
  58. - 📱 **One API, every target**: the same tools work across iOS and Android — simulators, emulators, and real devices.
  59. - 🧠 **No platform expertise required**: no XCUITest, no Espresso, no per-platform glue — describe the goal and the agent does it.
  60. - 🧰 **Full device control**: taps, swipes, and gestures; app install/launch/terminate; screen recording; hardware buttons; deep links; orientation.
  61. - 📊 **Structured, deterministic output**: reads real UI elements and extracts structured data, cutting the ambiguity of screenshot-only approaches.
  62. - 🪞 **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.
  63. <p align="center">
  64. <img alt="/mobile-mirror showing an iOS simulator beside a Claude Code session" src="docs/screenshots/mobile-mirror.png" width="800" />
  65. </p>
  66. ### 🎯 Platform Support
  67. | Target | Supported | Setup |
  68. |---|:---:|---|
  69. | iOS Simulator | ✅ | Xcode + a booted simulator (`xcrun simctl`) |
  70. | iOS Real Device | ✅ | Device connected over USB and trusted |
  71. | Android Emulator | ✅ | Android SDK + running emulator (`adb`) |
  72. | Android Real Device | ✅ | `adb` + USB debugging enabled & authorized |
  73. ## 🔧 Available MCP Tools
  74. ### Device Management
  75. - **`mobile_list_available_devices`** - List all available devices (simulators, emulators, and real devices)
  76. - **`mobile_get_screen_size`** - Get the screen size of the mobile device in pixels
  77. - **`mobile_get_orientation`** - Get the current screen orientation of the device
  78. - **`mobile_set_orientation`** - Change the screen orientation (portrait/landscape)
  79. - **`mobile_fold_device`** - Fold or unfold a foldable device (iPhone Duo simulators, foldable Android emulators)
  80. - **`mobile_set_location`** - Override the GPS location reported by the device, or clear the override
  81. - **`mobile_clipboard`** - Read or replace the device clipboard
  82. ### Remote Devices (Mobile Next Cloud)
  83. - **`mobile_login_to_cloud_provider`** - Authenticate this machine with the cloud device provider (browser-based device-code login)
  84. - **`mobile_list_remote_devices`** - List device models available to reserve from the cloud fleet
  85. - **`mobile_allocate_remote_device`** - Reserve a physical cloud device for exclusive use
  86. - **`mobile_release_remote_device`** - Release a reserved cloud device back to the fleet
  87. ### App Management
  88. - **`mobile_list_apps`** - List all installed apps on the device
  89. - **`mobile_get_foreground_app`** - Get the app currently in the foreground
  90. - **`mobile_launch_app`** - Launch an app using its package name
  91. - **`mobile_terminate_app`** - Stop and terminate a running app
  92. - **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
  93. - **`mobile_uninstall_app`** - Uninstall an app by its package name or bundle ID
  94. - **`mobile_clear_app_data`** - Clear an app's data so it starts fresh (Android and iOS Simulator)
  95. ### Screen Interaction
  96. - **`mobile_take_screenshot`** - Take a screenshot to understand what's on screen, optionally clipped to a region
  97. - **`mobile_save_screenshot`** - Save a screenshot to a file
  98. - **`mobile_list_elements_on_screen`** - List UI elements with their coordinates and properties
  99. - **`mobile_click_on_screen_at_coordinates`** - Click at specific x,y coordinates or on an element by its ref
  100. - **`mobile_double_tap_on_screen`** - Double-tap at specific coordinates or on an element by its ref
  101. - **`mobile_long_press_on_screen_at_coordinates`** - Long press at specific coordinates or on an element by its ref
  102. - **`mobile_drag_on_screen`** - Drag from one point or element ref to another, with an optional hold before moving
  103. - **`mobile_swipe_on_screen`** - Swipe in any direction (up, down, left, right)
  104. - **`mobile_start_screen_recording`** - Start recording the device screen to a video file
  105. - **`mobile_stop_screen_recording`** - Stop the active screen recording and save the video
  106. ### Input & Navigation
  107. - **`mobile_type_keys`** - Type text into focused elements with optional submit
  108. - **`mobile_press_button`** - Press device buttons (HOME, BACK, VOLUME_UP/DOWN, ENTER, etc.)
  109. - **`mobile_open_url`** - Open http/https URLs in the device browser
  110. ### Logs & Crash Reports
  111. - **`mobile_get_device_logs`** - Collect live device logs (logcat on Android, unified log on iOS), optionally saved to a file
  112. - **`mobile_list_crashes`** - List crash reports available on the device
  113. - **`mobile_get_crash`** - Get the full content of a crash report by its ID
  114. - **`mobile_batch_commands`** - Run multiple tools in sequence in a single call (e.g. click, type, click), with optional `delay` steps in between, optionally listing screen elements at the end
  115. ## 🏗️ Mobile MCP Architecture
  116. <p align="center">
  117. <a href="https://raw.githubusercontent.com/mobile-next/mobile-next-assets/refs/heads/main/mobile-mcp-arch-1.png">
  118. <img alt="mobile-mcp" src="https://raw.githubusercontent.com/mobile-next/mobile-next-assets/refs/heads/main/mobile-mcp-arch-1.png" width="600">
  119. </a>
  120. </p>
  121. ## 📚 Wiki page
  122. More details in our [wiki page](https://github.com/mobile-next/mobile-mcp/wiki) for setup, configuration and debugging related questions.
  123. ## Prerequisites
  124. What you will need to connect MCP with your agent and mobile devices:
  125. - [Xcode command line tools](https://developer.apple.com/xcode/resources/)
  126. - [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools)
  127. - [node.js](https://nodejs.org/en/download/) v20+
  128. - [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/)
  129. ## Installation and configuration
  130. To configure it by hand, this **standard config** works in most of the tools:
  131. ```json
  132. {
  133. "mcpServers": {
  134. "mobile-mcp": {
  135. "command": "npx",
  136. "args": ["-y", "@mobilenext/mobile-mcp@latest"]
  137. }
  138. }
  139. }
  140. ```
  141. <details>
  142. <summary>Amp</summary>
  143. Add via the Amp VS Code extension settings screen or by updating your `settings.json` file:
  144. ```json
  145. "amp.mcpServers": {
  146. "mobile-mcp": {
  147. "command": "npx",
  148. "args": [
  149. "@mobilenext/mobile-mcp@latest"
  150. ]
  151. }
  152. }
  153. ```
  154. **Amp CLI:**
  155. Run the following command in your terminal:
  156. ```bash
  157. amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
  158. ```
  159. </details>
  160. <details>
  161. <summary>Antigravity 2</summary>
  162. Antigravity doesn't have a CLI command to add MCP servers, so add it manually. Edit `~/.gemini/config/mcp_config.json` and add:
  163. ```json
  164. {
  165. "mcpServers": {
  166. "mobile-mcp": {
  167. "command": "npx",
  168. "args": ["-y", "@mobilenext/mobile-mcp@latest"]
  169. }
  170. }
  171. }
  172. ```
  173. </details>
  174. <details>
  175. <summary>Cline</summary>
  176. To setup Cline, just add the json above to your MCP settings file.
  177. [More in our wiki](https://github.com/mobile-next/mobile-mcp/wiki/Cline)
  178. </details>
  179. <details>
  180. <summary>Claude Code</summary>
  181. Install the plugin from inside Claude Code. It adds the Mobile MCP server and `/mobile-mirror`:
  182. ```
  183. /plugin marketplace add mobile-next/mobile-mcp
  184. /plugin install mobile-mcp@mobile-mcp
  185. ```
  186. `/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.
  187. If you can't use plugins, add only the MCP server with the Claude Code CLI:
  188. ```bash
  189. claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
  190. ```
  191. </details>
  192. <details>
  193. <summary>Claude Desktop</summary>
  194. Follow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user), use json configuration above.
  195. </details>
  196. <details>
  197. <summary>Codex</summary>
  198. Use the Codex CLI to add the Mobile MCP server:
  199. ```bash
  200. codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
  201. ```
  202. Alternatively, create or edit the configuration file `~/.codex/config.toml` and add:
  203. ```toml
  204. [mcp_servers.mobile-mcp]
  205. command = "npx"
  206. args = ["@mobilenext/mobile-mcp@latest"]
  207. ```
  208. For more information, see the Codex MCP documentation.
  209. </details>
  210. <details>
  211. <summary>Copilot</summary>
  212. Use the Copilot CLI to interactively add the Mobile MCP server:
  213. ```text
  214. /mcp add
  215. ```
  216. You can edit the configuration file `~/.copilot/mcp-config.json` and add:
  217. ```json
  218. {
  219. "mcpServers": {
  220. "mobile-mcp": {
  221. "type": "local",
  222. "command": "npx",
  223. "tools": [
  224. "*"
  225. ],
  226. "args": [
  227. "@mobilenext/mobile-mcp@latest"
  228. ]
  229. }
  230. }
  231. }
  232. ```
  233. For more information, see the Copilot CLI documentation.
  234. </details>
  235. <details>
  236. <summary>Cursor</summary>
  237. #### Click the button to install:
  238. [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=Mobile%20MCP&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2JpbGVuZXh0L21vYmlsZS1tY3BAbGF0ZXN0Il19)
  239. #### Or install manually:
  240. 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`.
  241. </details>
  242. <details>
  243. <summary>Gemini CLI</summary>
  244. Use the Gemini CLI to add the Mobile MCP server:
  245. ```bash
  246. gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
  247. ```
  248. </details>
  249. <details>
  250. <summary>Goose</summary>
  251. #### Click the button to install:
  252. [![Install in Goose](https://goose-docs.ai/img/extension-install-dark.svg)](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)
  253. #### Or install manually:
  254. 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".
  255. </details>
  256. <details>
  257. <summary>Kiro</summary>
  258. Follow the MCP Servers [documentation](https://kiro.dev/docs/mcp/). For example in `.kiro/settings/mcp.json`:
  259. ```json
  260. {
  261. "mcpServers": {
  262. "mobile-mcp": {
  263. "command": "npx",
  264. "args": [
  265. "@mobilenext/mobile-mcp@latest"
  266. ]
  267. }
  268. }
  269. }
  270. ```
  271. </details>
  272. <details>
  273. <summary>opencode</summary>
  274. Follow the MCP Servers documentation. For example in `~/.config/opencode/opencode.json`:
  275. ```json
  276. {
  277. "$schema": "https://opencode.ai/config.json",
  278. "mcp": {
  279. "servers": {
  280. "mobile-mcp": {
  281. "type": "local",
  282. "command": [
  283. "npx",
  284. "-y",
  285. "@mobilenext/mobile-mcp@latest"
  286. ]
  287. }
  288. }
  289. }
  290. }
  291. ```
  292. </details>
  293. <details>
  294. <summary>Windsurf</summary>
  295. Open Windsurf settings, navigate to MCP servers, and add a new server using the `command` type with:
  296. ```bash
  297. npx @mobilenext/mobile-mcp@latest
  298. ```
  299. Or add the standard config under `mcpServers` in your settings as shown above.
  300. </details>
  301. [Read more in our wiki](https://github.com/mobile-next/mobile-mcp/wiki)! 🚀
  302. ### ✅ Verify it works
  303. Once the server is configured, ask your agent to list devices:
  304. > list available devices
  305. 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).
  306. ### 🧪 From agent session to CI test
  307. Using Mobile MCP to automate a mobile app, or to test one? Tell your agent to write the flow as a **[Mobilewright](https://mobilewright.dev/?utm_source=mobile-mcp&utm_medium=readme&utm_campaign=agent-to-ci)** test. It becomes deterministic, and part of your CI/CD workflow.
  308. ```ts
  309. import { test, expect } from '@mobilewright/test';
  310. test('sign in', async ({ screen }) => {
  311. await screen.getByLabel('Email').fill('user@example.com');
  312. await screen.getByRole('button', { name: 'Sign In' }).tap();
  313. await expect(screen.getByText('Welcome back')).toBeVisible();
  314. });
  315. ```
  316. Start with `npm init mobilewright@latest`. The [step-by-step guide](docs/mobilewright-ci.md) goes from an agent session to a test running in GitHub Actions.
  317. ### ☁️ Scale up, use a cloud device
  318. Want to scale to hundreds of devices? Use Mobile MCP in your CI/CD pipeline?
  319. In your Agent, prompt:
  320. ```text
  321. log in to mobile next cloud and then show me which remote devices are available to me
  322. ```
  323. ### Streamable HTTP Server Mode
  324. 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:
  325. ```bash
  326. npx @mobilenext/mobile-mcp@latest --listen 3000
  327. ```
  328. This binds to `localhost:3000`. To bind to a specific interface:
  329. ```bash
  330. npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000
  331. ```
  332. 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.
  333. > **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.
  334. When binding to localhost, Host-header DNS rebinding protection is enabled automatically.
  335. #### Authorization
  336. To require Bearer token authorization on the HTTP server, set the `MOBILEMCP_AUTH` environment variable:
  337. ```bash
  338. MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000
  339. ```
  340. When set, all requests must include the header `Authorization: Bearer my-secret-token`. When unset, the server accepts unauthenticated connections and logs a warning.
  341. ### 🛠️ How to Use
  342. After adding the MCP server to your IDE/Client, you can instruct your AI assistant to use the available tools.
  343. 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.
  344. Be descriptive, straight to the point.
  345. ### ✨ Example Prompts
  346. #### Workflows
  347. You can specify detailed workflows in a single prompt, verify business logic, setup automations. You can go crazy:
  348. **Search for a video, comment, like and share it.**
  349. ```
  350. Find the video called " Beginner Recipe for Tonkotsu Ramen" by Way of
  351. Ramen, click on like video, after liking write a comment " this was
  352. delicious, will make it next Friday", share the video with the first
  353. contact in your whatsapp list.
  354. ```
  355. **Download a successful step counter app, register, setup workout and 5-star the app**
  356. ```
  357. Find and Download a free "Pomodoro" app that has more than 1k stars.
  358. Launch the app, register with my email, after registration find how to
  359. start a pomodoro timer. When the pomodoro timer started, go back to the
  360. app store and rate the app 5 stars, and leave a comment how useful the
  361. app is.
  362. ```
  363. **Search in Substack, read, highlight, comment and save an article**
  364. ```
  365. Open Substack website, search for "Latest trends in AI automation 2025",
  366. open the first article, highlight the section titled "Emerging AI trends",
  367. and save article to reading list for later review, comment a random
  368. paragraph summary.
  369. ```
  370. **Reserve a workout class, set timer**
  371. ```
  372. Open ClassPass, search for yoga classes tomorrow morning within 2 miles,
  373. book the highest-rated class at 7 AM, confirm reservation,
  374. setup a timer for the booked slot in the phone
  375. ```
  376. **Find a local event, setup calendar event**
  377. ```
  378. Open Eventbrite, search for AI startup meetup events happening this
  379. weekend in "Austin, TX", select the most popular one, register and RSVP
  380. yes to the event, setup a calendar event as a reminder.
  381. ```
  382. **Check weather forecast and send a Whatsapp/Telegram/Slack message**
  383. ```
  384. Open Weather app, check tomorrow's weather forecast for "Berlin", and
  385. send the summary via Whatsapp/Telegram/Slack to contact "Lauren Trown",
  386. thumbs up their response.
  387. ```
  388. - **Schedule a meeting in Zoom and share invite via email**
  389. ```
  390. Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
  391. 10AM with a duration of 1 hour, copy the invitation link, and send it via
  392. Gmail to contacts "team@example.com".
  393. ```
  394. ## Running & configuration
  395. ### Environment variables
  396. | Variable | Description | Example |
  397. |---|---|---|
  398. | `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` |
  399. | `MOBILEMCP_DISABLE_TELEMETRY` | Disable anonymous usage telemetry. | `MOBILEMCP_DISABLE_TELEMETRY=1` |
  400. | `MOBILEMCP_ALLOW_UNSAFE_URLS` | Allow `mobile_open_url` to open non-standard URL schemes (blocked by default). | `MOBILEMCP_ALLOW_UNSAFE_URLS=1` |
  401. | `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` |
  402. ### Simulators, Emulators, and Real Devices
  403. When launched, Mobile MCP can connect to:
  404. - iOS Simulators on macOS/Linux
  405. - Android Emulators on Linux/Windows/macOS
  406. - iOS or Android real devices (requires proper platform tools and drivers)
  407. Make sure you have your mobile platform SDKs (Xcode, Android SDK) installed and configured properly before running Mobile Next Mobile MCP.
  408. ### Telemetry
  409. Mobile MCP collects anonymous usage telemetry via PostHog and Scarf. To disable it, set the `MOBILEMCP_DISABLE_TELEMETRY` environment variable:
  410. ```bash
  411. MOBILEMCP_DISABLE_TELEMETRY=1 npx @mobilenext/mobile-mcp@latest
  412. ```
  413. For json configurations:
  414. ```json
  415. {
  416. "mcpServers": {
  417. "mobile-mcp": {
  418. "command": "npx",
  419. "args": ["-y", "@mobilenext/mobile-mcp@latest"],
  420. "env": {
  421. "MOBILEMCP_DISABLE_TELEMETRY": "1"
  422. }
  423. }
  424. }
  425. }
  426. ```
  427. ### Running in "headless" mode on Simulators/Emulators
  428. 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.
  429. For example, on Android:
  430. 1. Start an emulator (avdmanager / emulator command).
  431. 2. Run Mobile MCP with the desired flags
  432. On iOS, you'll need Xcode and to run the Simulator before using Mobile MCP with that simulator instance.
  433. - `xcrun simctl list`
  434. - `xcrun simctl boot "iPhone 16"`
  435. ## 🧩 Part of Mobile Next
  436. Mobile MCP is one piece of a toolkit for driving real mobile devices:
  437. - **[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.
  438. - **[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.
  439. - **[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.
  440. ## 🚀 Roadmap
  441. 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.
  442. ## 🤝 Contributing
  443. Contributions are welcome — code, docs, bug reports, and ideas.
  444. - ⭐ **[Star the repo](https://github.com/mobile-next/mobile-mcp)** — the easiest way to help others discover Mobile MCP.
  445. - Read [CONTRIBUTING.md](CONTRIBUTING.md) for how to build, test, and open a pull request.
  446. - Browse [open issues](https://github.com/mobile-next/mobile-mcp/issues) to find something to work on.
  447. - 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).
  448. Please also review our [Code of Conduct](CODE_OF_CONDUCT.md).
  449. # Thanks to all contributors ❤️
  450. ### We appreciate everyone who has helped improve this project.
  451. <a href = "https://github.com/mobile-next/mobile-mcp/graphs/contributors">
  452. <img src = "https://contrib.rocks/image?repo=mobile-next/mobile-mcp"/>
  453. </a>
  454. ## Privacy Policy
  455. Mobile MCP runs locally and communicates only with the devices you connect.
  456. See the Mobile Next privacy policy at https://mobilenext.ai/privacy for data
  457. collection, usage, retention, and contact information.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.