Mobile Mcp

Mobile Next - MCP server for Mobile Development and Automation | iOS, Android, Simulator, Emulator, and Real Devices

English | 日本語 | 简体中文

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

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.

Works with Claude Code, Codex, Gemini, GitHub Copilot, Antigravity — or any MCP-compatible client.

Run it against devices on your own machine, or against real iOS and Android devices in the cloud with Mobile Next Cloud — same tools, no local setup.

[Mobile Next Stars] [npm] [图片] [Install in VS Code] [wiki] [join on Slack]

[GitHub Trending Repository of the Day]

https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde

🚀 Quick start

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:

npx @mobilenext/mobile-mcp@latest install

Add --yes to configure every detected client without asking.

Manual setup per client: Installation and configuration

[mobile-mcp]

Main use cases

How we help to scale mobile automation:

• 📲 Native app automation (iOS and Android) for testing or data-entry scenarios.
• 📝 Scripted flows and form interactions without manually controlling simulators/emulators or real devices (iPhone, Samsung, Google Pixel etc)
• 🧭 Automating multi-step user journeys driven by an LLM
• 👆 General-purpose mobile application interaction for agent-based frameworks
• 🤖 Enables agent-to-agent communication for mobile automation usecases, data extraction

Main Features

• 🚀 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.
• 📱 One API, every target: the same tools work across iOS and Android — simulators, emulators, and real devices.
• 🧠 No platform expertise required: no XCUITest, no Espresso, no per-platform glue — describe the goal and the agent does it.
• 🧰 Full device control: taps, swipes, and gestures; app install/launch/terminate; screen recording; hardware buttons; deep links; orientation.
• 📊 Structured, deterministic output: reads real UI elements and extracts structured data, cutting the ambiguity of screenshot-only approaches.
• 🪞 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.

[/mobile-mirror showing an iOS simulator beside a Claude Code session]

🎯 Platform Support

🔧 Available MCP Tools

Device Management

• mobile_list_available_devices - List all available devices (simulators, emulators, and real devices)
• mobile_get_screen_size - Get the screen size of the mobile device in pixels
• mobile_get_orientation - Get the current screen orientation of the device
• mobile_set_orientation - Change the screen orientation (portrait/landscape)
• mobile_fold_device - Fold or unfold a foldable device (iPhone Duo simulators, foldable Android emulators)
• mobile_set_location - Override the GPS location reported by the device, or clear the override
• mobile_clipboard - Read or replace the device clipboard

Remote Devices (Mobile Next Cloud)

• mobile_login_to_cloud_provider - Authenticate this machine with the cloud device provider (browser-based device-code login)
• mobile_list_remote_devices - List device models available to reserve from the cloud fleet
• mobile_allocate_remote_device - Reserve a physical cloud device for exclusive use
• mobile_release_remote_device - Release a reserved cloud device back to the fleet

App Management

• mobile_list_apps - List all installed apps on the device
• mobile_get_foreground_app - Get the app currently in the foreground
• mobile_launch_app - Launch an app using its package name
• mobile_terminate_app - Stop and terminate a running app
• mobile_install_app - Install an app from file (.apk, .ipa, .app, .zip)
• mobile_uninstall_app - Uninstall an app by its package name or bundle ID
• mobile_clear_app_data - Clear an app's data so it starts fresh (Android and iOS Simulator)

Screen Interaction

• mobile_take_screenshot - Take a screenshot to understand what's on screen
• mobile_save_screenshot - Save a screenshot to a file
• mobile_list_elements_on_screen - List UI elements with their coordinates and properties
• mobile_click_on_screen_at_coordinates - Click at specific x,y coordinates or on an element by its ref
• mobile_double_tap_on_screen - Double-tap at specific coordinates or on an element by its ref
• mobile_long_press_on_screen_at_coordinates - Long press at specific coordinates or on an element by its ref
• mobile_swipe_on_screen - Swipe in any direction (up, down, left, right)
• mobile_start_screen_recording - Start recording the device screen to a video file
• mobile_stop_screen_recording - Stop the active screen recording and save the video

Input & Navigation

• mobile_type_keys - Type text into focused elements with optional submit
• mobile_press_button - Press device buttons (HOME, BACK, VOLUME_UP/DOWN, ENTER, etc.)
• mobile_open_url - Open http/https URLs in the device browser

Logs & Crash Reports

• mobile_get_device_logs - Collect live device logs (logcat on Android, unified log on iOS), optionally saved to a file
• mobile_list_crashes - List crash reports available on the device
• mobile_get_crash - Get the full content of a crash report by its ID
• mobile_batch_commands - Run multiple tools in sequence in a single call (e.g. click, type, click), optionally listing screen elements at the end

🏗️ Mobile MCP Architecture

[mobile-mcp]

📚 Wiki page

More details in our wiki page for setup, configuration and debugging related questions.

Prerequisites

What you will need to connect MCP with your agent and mobile devices:

• Xcode command line tools
• Android Platform Tools
• node.js v20+
• MCP supported foundational models or agents, like Claude MCP, OpenAI Agent SDK, Copilot Studio

Installation and configuration

To configure it by hand, this standard config works in most of the tools:

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

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

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

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

/plugin marketplace add mobile-next/mobile-mcp/plugin install mobile-mcp@mobile-mcp

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

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

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

/mcp add

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

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

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

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "mobile-mcp": {      "type": "local",      "command": [        "npx",        "@mobilenext/mobile-mcp@latest"      ],      "enabled": true    }  }}

npx @mobilenext/mobile-mcp@latest

Read more in our wiki! 🚀

✅ Verify it works

Once the server is configured, ask your agent to list devices:

list available devices

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) — for more help, check the wiki.

🧪 From agent session to CI test

Using Mobile MCP to automate a mobile app, or to test one? Tell your agent to write the flow as a Mobilewright test. It becomes deterministic, and part of your CI/CD workflow.

import { test, expect } from '@mobilewright/test';
test('sign in', async ({ screen }) => {  await screen.getByLabel('Email').fill('[email protected]');  await screen.getByRole('button', { name: 'Sign In' }).tap();  await expect(screen.getByText('Welcome back')).toBeVisible();});

Start with npm init mobilewright@latest. The step-by-step guide goes from an agent session to a test running in GitHub Actions.

☁️ Scale up, use a cloud device

Want to scale to hundreds of devices? Use Mobile MCP in your CI/CD pipeline?

In your Agent, prompt:

log in to mobile next cloud and then show me which remote devices are available to me

Streamable HTTP Server Mode

By default, Mobile MCP runs over stdio. To start a Streamable HTTP server instead, use the --listen flag:

npx @mobilenext/mobile-mcp@latest --listen 3000

This binds to localhost:3000. To bind to a specific interface:

npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000

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.

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.

When binding to localhost, Host-header DNS rebinding protection is enabled automatically.

Authorization

To require Bearer token authorization on the HTTP server, set the MOBILEMCP_AUTH environment variable:

MOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000

When set, all requests must include the header Authorization: Bearer my-secret-token. When unset, the server accepts unauthenticated connections and logs a warning.

🛠️ How to Use

After adding the MCP server to your IDE/Client, you can instruct your AI assistant to use the available tools. 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. Be descriptive, straight to the point.

✨ Example Prompts

Workflows

You can specify detailed workflows in a single prompt, verify business logic, setup automations. You can go crazy:

Search for a video, comment, like and share it.

Find the video called " Beginner Recipe for Tonkotsu Ramen" by Way ofRamen, click on like video, after liking write a comment " this wasdelicious, will make it next Friday", share the video with the firstcontact in your whatsapp list.

Download a successful step counter app, register, setup workout and 5-star the app

Find and Download a free "Pomodoro" app that has more than 1k stars.Launch the app, register with my email, after registration find how tostart a pomodoro timer. When the pomodoro timer started, go back to theapp store and rate the app 5 stars, and leave a comment how useful theapp is.

Search in Substack, read, highlight, comment and save an article

Open Substack website, search for "Latest trends in AI automation 2025",open the first article, highlight the section titled "Emerging AI trends",and save article to reading list for later review, comment a randomparagraph summary.

Reserve a workout class, set timer

Open ClassPass, search for yoga classes tomorrow morning within 2 miles,book the highest-rated class at 7 AM, confirm reservation,setup a timer for the booked slot in the phone

Find a local event, setup calendar event

Open Eventbrite, search for AI startup meetup events happening thisweekend in "Austin, TX", select the most popular one, register and RSVPyes to the event, setup a calendar event as a reminder.

Check weather forecast and send a Whatsapp/Telegram/Slack message

Open Weather app, check tomorrow's weather forecast for "Berlin", andsend the summary via Whatsapp/Telegram/Slack to contact "Lauren Trown",thumbs up their response.

• Schedule a meeting in Zoom and share invite via email

Open Zoom app, schedule a meeting titled "AI Hackathon" for tomorrow at10AM with a duration of 1 hour, copy the invitation link, and send it viaGmail to contacts "[email protected]".

Running & configuration

Environment variables

Simulators, Emulators, and Real Devices

When launched, Mobile MCP can connect to:

• iOS Simulators on macOS/Linux
• Android Emulators on Linux/Windows/macOS
• iOS or Android real devices (requires proper platform tools and drivers)

Make sure you have your mobile platform SDKs (Xcode, Android SDK) installed and configured properly before running Mobile Next Mobile MCP.

Telemetry

Mobile MCP collects anonymous usage telemetry via PostHog and Scarf. To disable it, set the MOBILEMCP_DISABLE_TELEMETRY environment variable:

MOBILEMCP_DISABLE_TELEMETRY=1 npx @mobilenext/mobile-mcp@latest

For json configurations:

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

Running in "headless" mode on Simulators/Emulators

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.

For example, on Android:

1. Start an emulator (avdmanager / emulator command).
2. Run Mobile MCP with the desired flags

On iOS, you'll need Xcode and to run the Simulator before using Mobile MCP with that simulator instance.

• xcrun simctl list
• xcrun simctl boot "iPhone 16"

🧩 Part of Mobile Next

Mobile MCP is one piece of a toolkit for driving real mobile devices:

• mobilewright — "Playwright for mobile." When you're ready to turn agent-driven exploration into repeatable, deterministic tests for iOS and Android, graduate to mobilewright.
• 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.
• Mobile Next Cloud — 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.

🚀 Roadmap

We're continuously improving Mobile MCP. See what we're building next in ROADMAP.md — priorities are shaped heavily by community feedback, so tell us what you'd like to see.

🤝 Contributing

Contributions are welcome — code, docs, bug reports, and ideas.

• ⭐ Star the repo — the easiest way to help others discover Mobile MCP.
• Read CONTRIBUTING.md for how to build, test, and open a pull request.
• Browse open issues to find something to work on.
• Questions and ideas are also welcome in our Slack community.

Please also review our Code of Conduct.

Thanks to all contributors ❤️

We appreciate everyone who has helped improve this project.

Privacy Policy

Mobile MCP runs locally and communicates only with the devices you connect. See the Mobile Next privacy policy at https://mobilenext.ai/privacy for data collection, usage, retention, and contact information.