Mobilerun

Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.

What can you do with Mobilerun?

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, iPhones through mobilerun-ios, or the iOS Simulator through the iOS Portal app.
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.

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

Remote (streamable-http)

Claude Code

claude mcp add --transport http mobilerun 'https://cloud.mobilerun.ai/api/mcp'

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "mobilerun": {
            "type": "http",
            "url": "https://cloud.mobilerun.ai/api/mcp"
        }
    }
}

Remote (streamable-http)

Claude Code

claude mcp add --transport http mobilerun 'https://api.mobilerun.ai/v1/mcp' --header 'Authorization: <Bearer dr_sk_... API key from cloud.mobilerun.ai (for CI and headless clients)>'

JSON configuration (Claude Desktop, Cursor, VS Code)

{
    "mcpServers": {
        "mobilerun": {
            "type": "http",
            "url": "https://api.mobilerun.ai/v1/mcp",
            "headers": {
                "Authorization": "<Bearer dr_sk_... API key from cloud.mobilerun.ai (for CI and headless clients)>"
            }
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

🎯 Platform Support
📦 Installation
🚀 Quickstart
⚙️ Features
☁️ Framework vs Cloud
🧩 Agent Skill
🎬 Demo Videos
💡 Example Use Cases
🌐 Part of Mobilerun
📚 Documentation
👥 Contributing
📄 License
Security Checks

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.

📕 Documentation · ☁️ Mobilerun Cloud · 🛡️ Mobile Harness

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

🎯 Platform Support

Target	Supported	Setup
Android Real Device	✅	`adb` or the Portal app
Android Emulator	✅	Running emulator (`adb`)
iOS Real Device	✅	`mobilerun-ios` over USB
iOS Simulator	✅	iOS Portal app
Android on Mobilerun Cloud	✅	Hosted phones or your own
iOS on Mobilerun Cloud	✅	Hosted iPhones or your own

📦 Installation

Note: Python 3.14 is not currently supported. Please use Python >=3.11,<3.14.

Install Mobilerun with uv:

# CLI usage
uv tool install mobilerun

# CLI + Python integration
uv pip install mobilerun

Most LLM providers are included by default. For Anthropic support, install the optional extra:

uv tool install "mobilerun[anthropic]"

🚀 Quickstart

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. For iOS, set up mobilerun-ios for an iPhone or the iOS Portal app for the simulator.

1. Install the Portal on your device

mobilerun setup

This installs the Mobilerun Portal app, enables its accessibility service, and prepares the device for local control.

2. Verify the connection

mobilerun ping

You should see confirmation that the Portal is installed and accessible.

3. Configure your LLM provider

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

mobilerun run "Open the settings app and tell me the Android version"

Useful run options:

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

Read the full framework documentation.

⚙️ Features

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, iPhones through mobilerun-ios, or the iOS Simulator through the iOS Portal app.
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:

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, iPhones, 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.

Shows browsing, app navigation, and result extraction from a natural-language task.

💡 Example Use Cases

Mobile app QA and regression testing
Guided workflows for non-technical users
Repetitive task automation on mobile devices
Event-driven automation from schedules, notifications, or custom triggers
Data extraction from native mobile apps
Running automations on multiple devices at once

🌐 Part of Mobilerun

Mobilerun is one piece of a toolkit for driving real phones with AI agents:

Mobilerun Portal: the Android app that lets you control and automate your phone.
mobilerun-ios: connects an iPhone over USB, either to this framework (--local) or to Mobilerun Cloud.
iOS Portal: the iOS app that lets the framework drive the iOS Simulator.
mobile-harness: an agent skill that lets Claude Code, Codex, and OpenClaw control Android, iOS, and cloud phones. App cards teach the agent how each app works, and shared memory keeps what it learns across tasks. It scores 100% on AndroidWorld and 98.34% on iOSWorld (benchmark results).
Mobilerun Cloud: cloud phones for AI agents. Hosted Android phones and dedicated iPhones, real numbers and inboxes for SMS and email codes, residential and mobile IPs in any region, scheduled and event triggers, and mobilerun VA, a no-code assistant for mobile tasks. Drive it through the REST API, Python and TypeScript SDKs, or MCP, and watch every step live.

📚 Documentation

👥 Contributing

Contributions are welcome. Please feel free to submit a pull request or open an issue.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

Security Checks

To help catch security issues before submitting changes, run:

bandit -r mobilerun
safety scan

Frequently asked questions

What is Mobilerun?

Let AI agents control Android and iOS devices on Mobilerun Cloud: screen, input, apps, workflows.

How do I install Mobilerun?

It runs as a remote server. In Claude Code: claude mcp add --transport http mobilerun 'https://cloud.mobilerun.ai/api/mcp'. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Mobilerun need an API key?

Yes. It expects Authorization, which you set in its configuration.

Is Mobilerun open source?

Yes. Its code is on GitHub under the Apache-2.0 license.

Who maintains Mobilerun?

It is published by droidrun. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Official MCP Registry
Publisher: droidrun
Category: AI and agents
Runs: Remote
GitHub stars: ★ 1
License: Apache-2.0
Language: TypeScript
Last commit: Oct 27, 2026
Open issues: 0
Version: 1.1.0
Published: Oct 27, 2026

io.github.droidrun/mobilerun

Similar servers

Acronis MCP The first real CLI for the Acronis Cyber Protect Cloud platform - every tenant, agent...
INITE Brain Long-term memory for AI agents: a bitemporal knowledge graph with cited answers.
WorldSignals Real-world events for agents: new companies, insolvencies, tenders, funding, layoffs, o...
digline Read, measure and explain LLM eval runs of a digline suite. Cannot promote a baseline.
Valuein — SEC EDGAR Fundamentals & Smart-Money Data Point-in-time, survivorship-free SEC EDGAR fundamentals + smart-money signals for AI ag...
Edgar — SEC Company Financials for AI Agents SEC financials for AI agents: statements for 8,000+ public companies. 5 tools, free, no...
Farmland — USDA Land Values & Cash Rents for AI Agents USDA farmland values and county cash rents for AI agents. NASS data, 3 tools, free, no ...
Magpie — USDA Ag Markets: Grain, Fertilizer, WASDE & Export Sales USDA farm data for AI agents: grain, fertilizer, WASDE, export sales. 27 tools, free, n...

AI and agents