Mobile MCP Setup for Android and iOS Device Automation
Start mobile MCP with one iOS Simulator or Android Emulator. First verify that the server can list the device and inspect its screen. Only after that baseline works should you enable taps, typing, app installs, or real-device workflows.
Start mobile MCP with one iOS Simulator or Android Emulator. First verify that the server can list the device and inspect its screen. Only after that baseline works should you enable taps, typing, app installs, or real-device workflows.
Table of contents
- What Mobile MCP controls
- Prepare Android or iOS prerequisites
- Install and connect the local server
- Prove device discovery and screen inspection
- Add interactions with bounded test data
- Fix device, accessibility, and PATH failures
- FAQ
What Mobile MCP controls
Mobile MCP provides one MCP server for mobile automation and development across iOS and Android. It covers device management, app management, screen interaction, and input or navigation through an MCP-supported model or agent.
Its preferred inspection path uses native accessibility snapshots where available. When those are not available, it can use screenshot-based coordinates as a fallback. This supports native app testing, data-entry flows, multi-step LLM-driven journeys, and structured extraction of visible on-screen data. See the Mobile MCP directory page for the current directory entry and connection details.
A safe first workflow is:
- Start one iOS Simulator or Android Emulator.
- Connect the local server.
- Ask the model or agent to list available devices.
- Inspect the selected device screen.
- Confirm that the returned screen state matches the visible simulator or emulator.
- Add one bounded interaction, such as opening an app or entering test text.
This order separates connection problems from interaction problems and establishes a baseline before introducing a real device, sensitive data, or a longer task. MCP uses a client-server architecture in which a client connects models to server tools and context. Read the MCP architecture overview.
Prepare Android or iOS prerequisites
For iOS, install the Xcode command line tools and use a connected iOS device or a running iOS Simulator. For Android, install Android Platform Tools or the Android SDK and use a connected Android device or a running Android Emulator.
You also need:
- Node.js v22 or later.
- An MCP-supported model or agent, such as Claude, OpenAI Agent SDK, or Copilot Studio.
- A device target that is already running or connected.
- A client capable of connecting to a local stdio MCP server.
For Android, Android Debug Bridge is the foundation for communicating with an attached device or emulator. Confirm that the Android tooling can see the target before diagnosing MCP itself. The Android documentation explains the role of adb and the device connection model. See the Android Debug Bridge documentation.
For iOS, start the Simulator from Xcode or connect a device through the normal Apple development workflow. The Apple Simulator documentation covers running an app in Simulator or on a device and is the relevant reference for confirming that the target is available. See Apple’s Simulator guidance.
Keep the first target simple. One simulator or emulator avoids ambiguity when several devices are available and makes screen mismatches easier to identify.
Install and connect the local server
Install the verified package with npx -y @mobilenext/mobile-mcp@latest, then configure your MCP client to launch that command over stdio. Mobile MCP uses stdio transport and does not require authentication.
The command is the complete verified install and connection instruction:
npx -y @mobilenext/mobile-mcp@latest
Do not add flags or substitute a different package name. The client should start the server as a local process and establish the MCP connection through standard input and output. Your selected model or agent then uses the server’s exposed mobile capabilities through the client.
The Cursor MCP client page is a practical next step if Cursor is your client. Whichever client you use, check that:
- The command is entered exactly as shown.
- Node.js v22+ is available to the client process.
- The client reports a connected MCP server.
- The simulator, emulator, or device is already available to the operating system.
- No unrelated server configuration is being tested at the same time.
If the client starts but shows no mobile target, treat that as a device-discovery issue first. If the client cannot start the process, inspect Node.js availability and the client’s MCP configuration before testing screen actions.
Prove device discovery and screen inspection
First ask the connected model or agent to list available mobile devices, then select one target and request a screen inspection. Continue only when the listed target and inspected screen agree with the simulator, emulator, or device you intended to use.
Use a short proof sequence:
- List devices.
- Select exactly one target.
- Inspect the current screen.
- Compare the returned state with the visible screen.
- Record the app or screen context before taking an action.
A native accessibility snapshot should provide structured information when the app exposes suitable accessibility data. If the snapshot is incomplete, the server may fall back to screenshot-based coordinates. Treat coordinate-based results as more sensitive to layout changes, orientation, and screen state.
Do not begin with a long journey. A simple screen with stable labels is enough to prove that the server, client, target, and inspection path are aligned. If the screen is wrong, stop and correct discovery rather than asking the model to guess.
MCP’s debugging guidance recommends isolating the failing layer and inspecting logs or protocol behavior systematically. Apply that principle here: first verify the client-server connection, then device visibility, then screen inspection, and only afterward interactions. Use the MCP debugging guide.
Add interactions with bounded test data
After discovery and inspection work, add one interaction using non-sensitive, reversible test data. Start with a single tap or short text entry, inspect the screen again, and confirm that the expected state changed.
A bounded test should specify:
- One target device.
- One app or screen.
- One intended action.
- Synthetic values rather than personal or production data.
- A clear expected result.
- A stopping point if the result differs from expectation.
For example, enter a dummy value into a test form, inspect the updated screen, and stop. Then test navigation, installation, or a multi-step journey separately. This makes failures attributable to one capability instead of a chain of uncertain actions.
Use real-device workflows only after the emulator or simulator path is predictable. Keep permissions, accounts, and app data limited to what the test needs. Never ask the agent to bypass authentication, permissions, TLS, or other security controls. MCP security guidance emphasizes controlling tool access, validating inputs, and limiting the impact of connected tools. Review the MCP security best practices.
If your broader task involves web pages inside a mobile app or a separate browser workflow, the browser automation capability may be the more appropriate next tool. Keep the mobile server focused on the device and app state it can inspect.
Fix device, accessibility, and PATH failures
Fix failures by identifying whether the problem is process startup, device visibility, screen inspection, or the interaction itself. Test each layer independently and return to the last confirmed state before changing configuration.
| Symptom | Likely boundary | Next check |
|---|---|---|
| Server does not start | Node.js or client configuration | Confirm Node.js v22+ and the exact npx command |
| Server connects but lists no device | Simulator, emulator, SDK, or device connection | Start one target and verify the platform tooling sees it |
| Device is listed but screen data is incomplete | Accessibility or screen-state issue | Inspect a simple screen; check whether screenshot fallback is being used |
| Tap or typing misses the target | Coordinate or layout mismatch | Reinspect the current screen and use stable, bounded test data |
| Several targets appear | Ambiguous device selection | Stop extra simulators or emulators and select one explicitly |
For Android, revisit Android Platform Tools, the Android SDK, and the target’s connection state. For iOS, revisit Xcode command line tools and confirm that the Simulator or connected device is running. If the client cannot find npx, remember that GUI applications may have a different PATH from your shell.
For accessibility failures, test a basic native screen before blaming the model. Custom controls may expose less structured information, causing the server to rely more on screenshots and coordinates. Reinspect after every state-changing action.
If configuration remains unclear, use the MCP config doctor as the next practical diagnostic step. Keep the original command unchanged and make one configuration change at a time.