Mobile MCP

1# Mobile Next - MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices
2 
3This 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).
4This 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 
6<h4 align="center">
7  <a href="https://github.com/mobile-next/mobile-mcp">
8    <img src="https://img.shields.io/github/stars/mobile-next/mobile-mcp" alt="Mobile Next Stars" />
9  </a>
10  <a href="https://github.com/mobile-next/mobile-mcp">
11    <img src="https://img.shields.io/github/contributors/mobile-next/mobile-mcp?color=green" alt="Mobile Next Downloads" />
12  </a>
13  <a href="https://www.npmjs.com/package/@mobilenext/mobile-mcp">
14    <img src="https://img.shields.io/npm/dm/@mobilenext/mobile-mcp?logo=npm&style=flat&color=red" alt="npm" />
15  </a>
16  <a href="https://github.com/mobile-next/mobile-mcp/releases">
17    <img src="https://img.shields.io/github/release/mobile-next/mobile-mcp" />
18  </a>
19  <a href="https://github.com/mobile-next/mobile-mcp/blob/main/LICENSE">
20    <img src="https://img.shields.io/badge/license-Apache 2.0-blue.svg" alt="Mobile MCP is released under the Apache-2.0 License" />
21  </a>
22  <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">
23    <img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code" />
24  </a>
25</h4>
26 
27<h4 align="center">
28  <a href="https://github.com/mobile-next/mobile-mcp/wiki">
29    <img src="https://img.shields.io/badge/documentation-wiki-blue" alt="wiki" />
30  </a>
31  <a href="https://mobilenexthq.com/join-slack">
32    <img src="https://img.shields.io/badge/join-Slack-blueviolet?logo=slack&style=flat" alt="join on Slack" />
33  </a>
34</h4>
35 
36https://github.com/user-attachments/assets/c4e89c4f-cc71-4424-8184-bdbc8c638fa1
37 
38<p align="center">
39    <a href="https://github.com/mobile-next/">
40        <img alt="mobile-mcp" src="https://raw.githubusercontent.com/mobile-next/mobile-next-assets/refs/heads/main/mobile-mcp-banner.png" width="600" />
41    </a>
42</p>
43 
44### 🚀 Mobile MCP Roadmap: Building the Future of Mobile
45 
46Join us on our journey as we continuously enhance Mobile MCP!
47Check out our detailed roadmap to see upcoming features, improvements, and milestones. Your feedback is invaluable in shaping the future of mobile automation.
48 
49👉 [Explore the Roadmap](https://github.com/orgs/mobile-next/projects/3)
50 
51 
52### Main use cases
53 
54How we help to scale mobile automation:
55 
56- 📲 Native app automation (iOS and Android) for testing or data-entry scenarios.
57- 📝 Scripted flows and form interactions without manually controlling simulators/emulators or real devices (iPhone, Samsung, Google Pixel etc)
58- 🧭 Automating multi-step user journeys driven by an LLM
59- 👆 General-purpose mobile application interaction for agent-based frameworks
60- 🤖 Enables agent-to-agent communication for mobile automation usecases, data extraction
61 
62## Main Features
63 
64- 🚀 **Fast and lightweight**: Uses native accessibility trees for most interactions, or screenshot based coordinates where a11y labels are not available.
65- 🤖 **LLM-friendly**: No computer vision model required in Accessibility (Snapshot).
66- 🧿 **Visual Sense**: Evaluates and analyses what's actually rendered on screen to decide the next action. If accessibility data or view-hierarchy coordinates are unavailable, it falls back to screenshot-based analysis.
67- 📊 **Deterministic tool application**: Reduces ambiguity found in purely screenshot-based approaches by relying on structured data whenever possible.
68- 📺 **Extract structured data**: Enables you to extract structred data from anything visible on screen.
69 
70### 🎯 Platform Support
71 
72| Platform | Supported |
73|----------|:---------:|
74| iOS Real Device | ✅ |
75| iOS Simulator | ✅ |
76| Android Real Device | ✅ |
77| Android Emulator | ✅ |
78 
79## 🔧 Available MCP Tools
80 
81<details>
82<summary>📱 <strong>Click to expand tool list</strong> - List of Mobile MCP tools for automation and development</summary>
83 
84> For detailed implementation and parameter specifications, see [`src/server.ts`](src/server.ts)
85 
86### Device Management
87- **`mobile_list_available_devices`** - List all available devices (simulators, emulators, and real devices)
88- **`mobile_get_screen_size`** - Get the screen size of the mobile device in pixels
89- **`mobile_get_orientation`** - Get the current screen orientation of the device
90- **`mobile_set_orientation`** - Change the screen orientation (portrait/landscape)
91 
92### App Management
93- **`mobile_list_apps`** - List all installed apps on the device
94- **`mobile_launch_app`** - Launch an app using its package name
95- **`mobile_terminate_app`** - Stop and terminate a running app
96- **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
97- **`mobile_uninstall_app`** - Uninstall an app using bundle ID or package name
98 
99### Screen Interaction
100- **`mobile_take_screenshot`** - Take a screenshot to understand what's on screen
101- **`mobile_save_screenshot`** - Save a screenshot to a file
102- **`mobile_list_elements_on_screen`** - List UI elements with their coordinates and properties
103- **`mobile_click_on_screen_at_coordinates`** - Click at specific x,y coordinates
104- **`mobile_double_tap_on_screen`** - Double-tap at specific coordinates
105- **`mobile_long_press_on_screen_at_coordinates`** - Long press at specific coordinates
106- **`mobile_swipe_on_screen`** - Swipe in any direction (up, down, left, right)
107 
108### Input & Navigation
109- **`mobile_type_keys`** - Type text into focused elements with optional submit
110- **`mobile_press_button`** - Press device buttons (HOME, BACK, VOLUME_UP/DOWN, ENTER, etc.)
111- **`mobile_open_url`** - Open URLs in the device browser
112 
113### Platform Support
114- **iOS**: Simulators and real devices via native accessibility and WebDriverAgent
115- **Android**: Emulators and real devices via ADB and UI Automator
116- **Cross-platform**: Unified API works across both iOS and Android
117 
118</details>
119 
120## 🏗️ Mobile MCP Architecture
121 
122<p align="center">
123    <a href="https://raw.githubusercontent.com/mobile-next/mobile-next-assets/refs/heads/main/mobile-mcp-arch-1.png">
124        <img alt="mobile-mcp" src="https://raw.githubusercontent.com/mobile-next/mobile-next-assets/refs/heads/main/mobile-mcp-arch-1.png" width="600">
125    </a>
126</p>
127 
128 
129## 📚 Wiki page
130 
131More details in our [wiki page](https://github.com/mobile-next/mobile-mcp/wiki) for setup, configuration and debugging related questions.
132 
133 
134## Installation and configuration
135 
136**Standard config** works in most of the tools:
137 
138```json
139{
140  "mcpServers": {
141    "mobile-mcp": {
142      "command": "npx",
143      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
144    }
145  }
146}
147```
148 
149<details>
150<summary>Amp</summary>
151 
152Add via the Amp VS Code extension settings screen or by updating your `settings.json` file:
153 
154```json
155"amp.mcpServers": {
156  "mobile-mcp": {
157    "command": "npx",
158    "args": [
159      "@mobilenext/mobile-mcp@latest"
160    ]
161  }
162}
163```
164 
165**Amp CLI:**
166 
167Run the following command in your terminal:
168 
169```bash
170amp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest
171```
172 
173</details>
174 
175<details>
176<summary>Cline</summary>
177 
178To setup Cline, just add the json above to your MCP settings file.
179 
180[More in our wiki](https://github.com/mobile-next/mobile-mcp/wiki/Cline)
181 
182</details>
183 
184<details>
185<summary>Claude Code</summary>
186 
187Use the Claude Code CLI to add the Mobile MCP server:
188 
189```bash
190claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
191```
192</details>
193 
194<details>
195<summary>Claude Desktop</summary>
196 
197Follow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user), use json configuration above.
198 
199</details>
200 
201<details>
202<summary>Codex</summary>
203 
204Use the Codex CLI to add the Mobile MCP server:
205 
206```bash
207codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
208```
209 
210Alternatively, create or edit the configuration file `~/.codex/config.toml` and add:
211 
212```toml
213[mcp_servers.mobile-mcp]
214command = "npx"
215args = ["@mobilenext/mobile-mcp@latest"]
216```
217 
218For more information, see the Codex MCP documentation.
219 
220</details>
221 
222<details>
223<summary>Copilot</summary>
224 
225Use the Copilot CLI to interactively add the Mobile MCP server:
226 
227```text
228/mcp add
229```
230 
231You can edit the configuration file `~/.copilot/mcp-config.json` and add:
232 
233```json
234{
235  "mcpServers": {
236    "mobile-mcp": {
237      "type": "local",
238      "command": "npx",
239      "tools": [
240        "*"
241      ],
242      "args": [
243        "@mobilenext/mobile-mcp@latest"
244      ]
245    }
246  }
247}
248```
249 
250For more information, see the Copilot CLI documentation.
251 
252</details>
253 
254<details>
255<summary>Cursor</summary>
256 
257#### Click the button to install:
258 
259[<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)
260 
261#### Or install manually:
262 
263Go 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`.
264 
265</details>
266 
267<details>
268<summary>Gemini CLI</summary>
269 
270Use the Gemini CLI to add the Mobile MCP server:
271 
272```bash
273gemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest
274```
275 
276</details>
277 
278<details>
279<summary>Goose</summary>
280 
281#### Click the button to install:
282 
283[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/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)
284 
285#### Or install manually:
286 
287Go 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".
288 
289</details>
290 
291<details>
292<summary>Kiro</summary>
293 
294Follow the MCP Servers [documentation](https://kiro.dev/docs/mcp/). For example in `.kiro/settings/mcp.json`:
295 
296```json
297{
298  "mcpServers": {
299    "mobile-mcp": {
300      "command": "npx",
301      "args": [
302        "@mobilenext/mobile-mcp@latest"
303      ]
304    }
305  }
306}
307```
308 
309</details>
310 
311<details>
312<summary>opencode</summary>
313 
314Follow the MCP Servers documentation. For example in `~/.config/opencode/opencode.json`:
315 
316```json
317{
318  "$schema": "https://opencode.ai/config.json",
319  "mcp": {
320    "mobile-mcp": {
321      "type": "local",
322      "command": [
323        "npx",
324        "@mobilenext/mobile-mcp@latest"
325      ],
326      "enabled": true
327    }
328  }
329}
330```
331 
332</details>
333 
334<details>
335<summary>Qodo Gen</summary>
336 
337Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.
338 
339Click <code>Save</code>.
340 
341</details>
342 
343 
344<details>
345<summary>Windsurf</summary>
346 
347Open Windsurf settings, navigate to MCP servers, and add a new server using the `command` type with:
348 
349```bash
350npx @mobilenext/mobile-mcp@latest
351```
352 
353Or add the standard config under `mcpServers` in your settings as shown above.
354 
355</details>
356 
357 
358[Read more in our wiki](https://github.com/mobile-next/mobile-mcp/wiki)! 🚀
359 
360 
361### 🛠️ How to Use 📝
362 
363After adding the MCP server to your IDE/Client, you can instruct your AI assistant to use the available tools.
364For example, in Cursor's agent mode, you could use the prompts below to quickly validate, test and iterate on UI intereactions, read information from screen, go through complex workflows.
365Be descriptive, straight to the point.
366 
367### ✨ Example Prompts
368 
369#### Workflows
370 
371You can specifiy detailed workflows in a single prompt, verify business logic, setup automations. You can go crazy:
372 
373**Search for a video, comment, like and share it.**
374```
375Find the video called " Beginner Recipe for Tonkotsu Ramen" by Way of
376Ramen, click on like video, after liking write a comment " this was
377delicious, will make it next Friday", share the video with the first
378contact in your whatsapp list.
379```
380 
381**Download a successful step counter app, register, setup workout and 5-star the app**
382```
383Find and Download a free "Pomodoro" app that has more than 1k stars.
384Launch the app, register with my email, after registration find how to
385start a pomodoro timer. When the pomodoro timer started, go back to the
386app store and rate the app 5 stars, and leave a comment how useful the
387app is.
388```
389 
390**Search in Substack, read, highlight, comment and save an article**
391```
392Open Substack website, search for "Latest trends in AI automation 2025",
393open the first article, highlight the section titled "Emerging AI trends",
394and save article to reading list for later review, comment a random
395paragraph summary.
396```
397 
398**Reserve a workout class, set timer**
399```
400Open ClassPass, search for yoga classes tomorrow morning within 2 miles,
401book the highest-rated class at 7 AM, confirm reservation,
402setup a timer for the booked slot in the phone
403```
404 
405**Find a local event, setup calendar event**
406```
407Open Eventbrite, search for AI startup meetup events happening this
408weekend in "Austin, TX", select the most popular one, register and RSVP
409yes to the event, setup a calendar event as a reminder.
410```
411 
412**Check weather forecast and send a Whatsapp/Telegram/Slack message**
413```
414Open Weather app, check tomorrow's weather forecast for "Berlin", and
415send the summary via Whatsapp/Telegram/Slack to contact "Lauren Trown",
416thumbs up their response.
417```
418 
419- **Schedule a meeting in Zoom and share invite via email**
420```
421Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at
42210AM with a duration of 1 hour, copy the invitation link, and send it via
423Gmail to contacts "team@example.com".
424```
425[More prompt examples can be found here.](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)
426 
427## Prerequisites
428 
429What you will need to connect MCP with your agent and mobile devices:
430 
431- [Xcode command line tools](https://developer.apple.com/xcode/resources/)
432- [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools)
433- [node.js](https://nodejs.org/en/download/) v22+
434- [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/)
435 
436### Simulators, Emulators, and Real Devices
437 
438When launched, Mobile MCP can connect to:
439- iOS Simulators on macOS/Linux
440- Android Emulators on Linux/Windows/macOS
441- iOS or Android real devices (requires proper platform tools and drivers)
442 
443Make sure you have your mobile platform SDKs (Xcode, Android SDK) installed and configured properly before running Mobile Next Mobile MCP.
444 
445### Running in "headless" mode on Simulators/Emulators
446 
447When you do not have a real device connected to your machine, you can run Mobile MCP with an emulator or simulator in the background.
448 
449For example, on Android:
4501. Start an emulator (avdmanager / emulator command).
4512. Run Mobile MCP with the desired flags
452 
453On iOS, you'll need Xcode and to run the Simulator before using Mobile MCP with that simulator instance.
454- `xcrun simctl list`
455- `xcrun simctl boot "iPhone 16"`
456 
457# Thanks to all contributors ❤️
458 
459### We appreciate everyone who has helped improve this project.
460 
461  <a href = "https://github.com/mobile-next/mobile-mcp/graphs/contributors">
462   <img src = "https://contrib.rocks/image?repo=mobile-next/mobile-mcp"/>
463 </a>
464