Control real Android and iOS devices with LLM agents — tap, swipe, type, automate flows.
io.github.droidrun/mobilerun MCP Server
This MCP server provides an open-source framework for controlling real Android and iOS devices using LLM agents. It exposes mobile-native capabilities for inspecting UI state, understanding screenshots, and performing tap, swipe, and type actions, including planning and executing multi-step workflows with results returned via a CLI or Python API.
🛠️ Key Features
Control real Android and iOS devices
Inspect UI state and understand screenshots
Mobile-native actions: tap, swipe, type
Plan and run multi-step workflows
Return results through CLI or Python API
🚀 Use Cases
Building LLM agent workflows that interact with mobile UIs
Automating multi-step flows on Android and iOS device screens
⚡ Developer Benefits
Developer access via CLI and Python API
Agent integration with UI state and screenshot understanding
⚠️ Limitations
No tool count or additional API details are provided in the available source data.
Mobilerun is an open-source framework for controlling Android and iOS devices with LLM agents.
It gives agents mobile-native tools to inspect UI state, understand screenshots, tap, swipe, type, plan multi-step workflows, and return results through a CLI or Python API.
Mobilerun automating a phone with natural language
🤖 Control Android and iOS devices with natural language commands
🔀 Use OpenAI, Anthropic, Gemini, xAI, Ollama, DeepSeek, OpenRouter, and OpenAI-compatible models
🧠 Run direct tasks or enable reasoning mode for complex multi-step automation
💻 Automate from the CLI, a terminal UI, Docker, or Python code
🐍 Extend agents with custom tools, structured output, app cards, and credentials
📸 Combine accessibility trees with screenshots for visual understanding
Trace execution with Arize Phoenix or Langfuse
Use the framework when you want to run the agent on your machine. Use Mobilerun Cloud when you want a ready-to-go solution for your local phones or cloud-hosted virtual/physical phones, managed infrastructure, and API-driven device workflows without running the agent on your local machine. Check out our benchmark results.
📦 Installation
Note: Python 3.14 is not currently supported. Please use Python >=3.11,<3.14.
Most LLM providers are included by default. For Anthropic support, install the optional extra:
bash
uv tool install "mobilerun[anthropic]"
🚀 Quickstart
bash
uv tool install mobilerun
mobilerun setup
mobilerun configure
mobilerun run "Open settings and turn on dark mode"
Before starting, make sure you have ADB installed and an Android device with Developer options and USB debugging enabled. iOS setup is supported separately through the iOS Portal flow.
1. Install the Portal on your device
bash
mobilerun setup
This installs the Mobilerun Portal app, enables its accessibility service, and prepares the device for local control.
2. Verify the connection
bash
mobilerun ping
You should see confirmation that the Portal is installed and accessible.
3. Configure your LLM provider
bash
mobilerun configure
The wizard walks you through choosing a provider, auth method, and model. You can also use provider environment variables such as GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, XAI_API_KEY, or MINIMAX_API_KEY.
4. Run your first command
bash
mobilerun run "Open the settings app and tell me the Android version"
Useful run options:
bash
mobilerun run "Open settings and turn on dark mode"
mobilerun run "What app is currently open?" --vision
mobilerun run "Find a contact named John and send him an email" --reasoning
mobilerun run "Take a screenshot" --ios
mobilerun run "Open Settings" --steps 30 --debug
CLI: Run one-off natural language tasks, inspect devices, replay macros, and debug from the terminal.
Python API: Build custom mobile automation workflows with Python and use custom tools.
Android and iOS support: Control Android through the Portal app or target iOS through the iOS Portal flow.
Portal-based control: Use UI trees, screenshots, text input, gestures, app launching, and device state from the Portal runtime.
Vision mode: Send screenshots to the LLM with --vision, or use screenshot-only control with --vision-only (useful for the apps that do not have a11y tree information).
Reasoning mode: Use --reasoning for manager-executor planning on longer or more complex tasks.
Tracing and telemetry: Debug execution with Arize Phoenix, Langfuse, saved trajectories, and detailed logs.
Structured output: Return structured data from mobile workflows.
App cards and custom tools: Add app-specific guidance to make agent perform better on your use-cases.
Docker: Run Mobilerun in a container for repeatable local environments.
☁️ Framework vs Cloud
Mobilerun Framework
Mobilerun Cloud
Best for
Running agents locally on your own machine and devices
Ready-to-go local phone control, hosted real or virtual devices, API workflows, and managed device operations
Runtime
Your machine
Mobilerun-managed infrastructure
Interface
CLI, Docker, and Python API
Dashboard, REST API, SDKs, and hosted devices
Use the framework when you want full local control of the agent runtime. Use Mobilerun Cloud when you want managed devices, fleet workflows, or cloud APIs without running the agent locally. Learn more in the framework overview and the cloud docs.
Which should I choose?
Choose Mobilerun Framework for local agent execution and code-level control.
Choose Mobilerun Cloud for managed phones, APIs, and scale without running agents locally.
Cloud Device Types
Device type
What it is
Best for
Personal
Your own hardware connected to Mobilerun Cloud
Quick automation on devices you own
Cloud Phone (Hosted)
Instantly available cloud-hosted phone
Scalable hosted automation
Physical Phone (Hosted)
Real hardware with stronger identity characteristics
Workflows that need high device authenticity and trust
Automate WhatsApp on a Cloud Phone
Generate leads with Google Maps on a Cloud Phone
🧩 Agent Skill
Give Claude Code, Codex, or another coding agent direct control of Android and iOS devices with the mobile-harness skill. Copy paste it into your agent:
text
Set up https://github.com/droidrun/mobile-harness for me.
Read `install.md` and follow the steps to install `mobile-harness`.
The skill teaches the agent to drive local devices (ADB, Portal, iOS Simulator) and Mobilerun Cloud phones.
🎬 Demo Videos
Book accommodation from a prompt
Shows multi-step navigation, text input, and app-state reasoning while Mobilerun searches for accommodation.
