mobile-agent MCP server
Commit Nov 15, 2026Drives Android devices, emulators, iOS Simulators, and physical iPhones for AI agents using a live screen mirror and accessibility tree.
Also known as gesposito/mobile-agent
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is mobile-agent MCP?
mobile-agent drives Android devices, emulators, iOS Simulators, and physical iPhones for AI agents using a live screen mirror and accessibility tree.
Summary generated from the project's README
About mobile-agent MCP server
Automating mobile device interactions for AI agents is what mobile-agent enables by providing a bridge between LLM clients and mobile operating systems. It allows developers to drive Android devices, Android emulators, iOS Simulators, and physical iPhones through a live screen mirror and accessibility tree. By using a daemon that maintains snapshots of windows and frame callbacks, the system avoids the latency of reading the device for every individual request.
For Android, the system uses a single-dex agent pushed via adb that runs as the shell user without requiring an installed APK. On iOS, the driver operates from the host, using a Rust reader for the accessibility tree on Simulators, while physical iPhones utilize a built-in Rust runner started through the phone's test manager. This setup requires specific environments, such as Xcode for iOS drivers or the Android SDK platform-tools for Android. The mobile-agent-mcp server provides these capabilities to MCP clients using specialized tools and agent surfaces.
What you can do with it
- 1Automate Android emulator testingAn AI agent can perform tasks on an Android emulator using the fast path through the gRPC controller.
- 2Control physical iPhones via hostDevelopers can drive a physical iPhone from a host machine using a runner signed for a development team.
- 3Integrate mobile control into ClaudeYou can add mobile device driving capabilities to Claude Code by adding the MCP server via stdio.
- 4Execute Android shell commandsThe system can run an agent on Android devices as the shell user without installing any extra APKs.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANDROID_HOMEMOBILE_AGENT_DRIVERS
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegesposito/mobile-agent is public and reachablegithub.com/gesposito/mobile-agent ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/gesposito/mobile-agent ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmobile-agent
mobile-agent drives Android devices, Android emulators, iOS Simulators and physical iPhones for AI agents, and is designed around the latency of each tap-and-observe step. A daemon keeps a live mirror of every attached screen (its windows, accessibility tree and latest frame), updates it from the platform's change events and frame callbacks, and answers snapshots, waits and settle checks from that mirror instead of reading the device and sleeping on every request. On Android, a single-dex agent pushed over adb runs as the shell user under app_process and holds the device's UI automation role: no APK is installed and no instrumentation runs. On the iOS Simulator the driver works from the host: input goes through the Simulator's dtuhidd HID service, frames come from the display's IOSurface, and the accessibility tree comes from a Rust reader that the daemon spawns into the Simulator, with no XCTest runner and nothing installed. A physical iPhone's tree can be read only from an XCTest runner, so there a Rust runner built in this repository, started through the phone's test manager and kept for the session, serves the tree and text entry over the same device protocol, while the driver does the rest from the host: input through the developer disk image's dtuhidd, frames from screenshots it polls, and the phone's services over a CoreDevice tunnel it opens in its own process, without root or a helper. The mobile-agent CLI follows agent-browser's command grammar, @eN refs and JSON envelope, so prompts and skills written for agent-browser carry over where devices have the same concepts, and the mobile-agent-mcp server gives an MCP client the same tools, refs and replies (Agent surfaces).
Status. Experimental and pre-release: alphas of the three binaries are released on GitHub for Macs with Apple silicon and for Linux and packed for npm as @mobileagent/cli (Install), its crates are on crates.io (Crates), and main is the version CI builds and tests on macOS and Linux; the command-line and MCP interfaces may change between alphas. The drivers rely on private Apple and hidden Android interfaces, which makes this development tooling, never something to ship inside an app (Status and limitations). It is under the MIT License (LICENSE, THIRD-PARTY-NOTICES.md); CONTRIBUTING.md says how a change is made and checked, SECURITY.md how to report a vulnerability, and CHANGELOG.md what has changed.
Supported platforms
| Platform | Status | Tested on |
|---|---|---|
| macOS host | Simulator, Android and physical iPhone drivers, the iPhone's only when MOBILE_AGENT_DRIVERS names ios |
macOS 26.6.2, Apple M1 Max |
| Linux host | Android driver only; the Simulator and iPhone drivers build as stubs | CI builds and tests it on ubuntu-latest, without a device |
| Xcode | for the Simulator driver, 26.0 up to, not including, 28; other versions are refused with unsupported_xcode. The iPhone's runner is built from Xcode's XCTRunner.app and iPhoneOS SDK, tried with 27.0 alone |
Xcode 27.0 (27A266a); CI also builds with Xcode 26 |
| iOS Simulator | booted Simulators; no gate on the runtime version | iOS 26.5 (23F77), iPhone 17; iOS 27.0 in CI's device tests, on the xcode-27 image |
| Android emulator | fast path through the emulator's gRPC controller when it answers, the agent's path with --emulator-controller off |
API 36, arm64, Pixel 8 profile, Android Emulator 37.1.11 |
| Android agent | minimum API 26: the dex is built with --min-api 26, and a platform member that exists only from a later level is read behind a check of the level (agent-android/src/dev/mobileagent/agent/Levels.kt) |
API 36 on the emulator; API 27 (Android 8.1) on a Nexus 5X, from agent 0.4.3 |
| Physical Android device | through the same agent, without a frame stream: taps and screenshots go through the agent | a Nexus 5X on Android 8.1 (API 27), a user build (reports/10.3-physical-android.md) |
| Physical iPhone | on USB, through a runner signed for a paid development team (Quick start); iOS 17.4 up to, not including, 27, other versions refused with unsupported_ios; input from the host from iOS 18, through the runner below it; built and measured for iOS 26, whose dtuhidd takes the host's input without a display stream, while iOS 27's, which needs one, is a later path (crates/ios/README.md, Compatibility) |
an iPhone SE (3rd generation) on iOS 26.6.2 under Xcode 27.0, with idevice 0.1.68 (reports/11.1-ios-device.md) |
CI (.github/workflows/ci.yml) validates and runs no benchmark; the benchmarks have a workflow of their own, which never runs per push (How measurements are made), and so do the device-backed tests, .github/workflows/device-tests.yml, weekly and on dispatch, which can narrow a run to one job, one package and a test filter: the workspace's tests on a fresh iPhone 17 Simulator of the xcode-27 image and on an API 36 emulator on Linux, with the fixtures installed, the gating variables set and MOBILE_AGENT_HOST_GATES=off, under which the tests' millisecond bounds, measured on a quiet developer Mac, are printed rather than judged (design D1 of openspec/changes/archive/2026-11-05-pass-4-fixes). ci.yml runs just validate in three jobs: Linux, which also builds the Android agent and the Compose fixture; macOS with Xcode 26 on GitHub's macos-26 image; and macOS with Xcode 27 on its xcode-27 image. A fourth, Audit, lints the workflows with actionlint, audits them with zizmor, its online audits included, checks the dependencies' advisories, licenses, bans and sources with cargo-deny (deny.toml), and runs the publish scan and openspec validate --all --strict. Before them, a job classifies a pull request with scripts/ci-changes.sh: one that changes documentation alone, Markdown anywhere, docs/, openspec/, the licenses and the issue templates, runs Audit alone, the Linux and macOS jobs skipped by their if, so that their required checks read skipped, which passes them; a push to main and a dispatch run every job. Every job starts without permissions and reads only what it needs, every action is pinned to a full commit SHA, no checkout keeps its credentials, and the tools come from lockfiles or from releases pinned with their SHA-256 (docs/research/open-sourcing.md). Each macOS job keeps the image's default Xcode when it has that major version and otherwise selects the newest Xcode_<major>*.app. The macOS jobs build and test the iPhone driver (crates/ios, on its fake device) and the runner's crate (agent-ios, on the host); nothing runs against a phone, the device tests skipping without MOBILE_AGENT_IOS_UDID, and the signed runner bundle is not built there, since just agent-ios-build skips with SKIP_AGENT_BUILD=1 or without MOBILE_AGENT_IOS_TEAM, as just agent-build skips the Android agent with SKIP_AGENT_BUILD=1. The spikes and every measurement ran on Xcode 27.0 with CoreSimulator 1171.7 and iOS 26.5, and so did the Simulator integration tests, which the device tests also run on the xcode-27 image's iOS 27.0. Nothing has run on Xcode 26, where input would be touch only, through the older Indigo transport (crates/simulator/README.md, Compatibility).
Install
Experimental, pre-release: the drivers use private Apple Simulator frameworks, Apple's developer services on an iPhone and hidden Android APIs; the command-line and MCP interfaces may change between alphas.
Three ways, the first for an MCP client: npm, the release's tarballs, or crates.io.
npm. @mobileagent/cli gives the three commands through a small launcher and installs the binaries of the host's target from one platform package, @mobileagent/cli-darwin-arm64, -linux-x64 or -linux-arm64, as an optional dependency, with no install script; the binaries are the release's tarballs' (below), and from the second version on npm the release workflow publishes the packages with npm's provenance (npm/cli/README.md). It needs Node 22 or newer on the targets below. The package has three commands, so npx takes it with --package and the command by its name, and npx mobile-agent-mcp alone would fetch an unrelated package of that name; @alpha is the newest alpha, and @mobileagent/cli@<version> keeps one:
claude mcp add --transport stdio mobile-agent -- npx -y --package=@mobileagent/cli@alpha mobile-agent-mcp # Claude Code
npx -y --package=@mobileagent/cli@alpha mobile-agent --version # mobile-agent <version> (<the commit's first 12 digits>)
npm install --global @mobileagent/cli@alpha # mobile-agent, mobile-agent-daemon and mobile-agent-mcp on PATH
Codex's, Claude Desktop's and Cursor's entries are in Agent surfaces. On another host, or when optional dependencies are omitted, a command prints the supported platforms and exits 1.
The release's tarballs. Each pre-release on the releases page holds a tarball per target, mobile-agent-<version>-<target>.tar.gz, with mobile-agent, mobile-agent-daemon, mobile-agent-mcp, THIRD-PARTY-NOTICES.md and the four files' SHA256SUMS, and beside it the tarball's own sum, <tarball>.sha256. The tarball and its three binaries carry an attestation of the release workflow's run that built them (.github/workflows/release.yml), and the release is immutable: its tag and assets cannot change.
| Target | Host | Drives |
|---|---|---|
aarch64-apple-darwin |
a Mac with Apple silicon | iOS Simulators and physical iPhones, through Xcode with an iOS Simulator runtime, and Android |
x86_64-unknown-linux-gnu |
x86_64 Linux with glibc 2.35 or newer | Android only |
aarch64-unknown-linux-gnu |
aarch64 Linux with glibc 2.35 or newer | Android only |
With GitHub's CLI, gh, signed in:
version=0.1.0-alpha.1
target=aarch64-apple-darwin # or x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu
name="mobile-agent-$version-$target"
gh release download "v$version" -R gesposito/mobile-agent -p "$name.tar.gz" -p "$name.tar.gz.sha256"
gh attestation verify "$name.tar.gz" -R gesposito/mobile-agent # built by this repository's release workflow
shasum -a 256 -c "$name.tar.gz.sha256" # sha256sum -c on a Linux without shasum
tar -xzf "$name.tar.gz"
(cd "$name" && shasum -a 256 -c SHA256SUMS)
mkdir -p ~/.local/bin
cp "$name/mobile-agent" "$name/mobile-agent-daemon" "$name/mobile-agent-mcp" ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH" # and in the shell's profile; the CLI starts the daemon it finds beside itself
mobile-agent --version # mobile-agent 0.1.0-alpha.1 (<the commit's first 12 digits>)
gh release verify "v$version" -R gesposito/mobile-agentchecks that the release is immutable and carries its attestation, andgh release verify-asset "v$version" "$name.tar.gz" -R gesposito/mobile-agentthat the tarball is the one it holds.gh attestation verifyalso takes each binary, and--signer-workflow gesposito/mobile-agent/.github/workflows/release.ymland--source-digest <commit>narrow who signed it.- The binaries are signed ad hoc by the linker, not notarized. A browser marks what it downloads as quarantined, and macOS may then refuse to run them;
gh, as above, andcurl -LO https://github.com/gesposito/mobile-agent/releases/download/v$version/$name.tar.gzmark nothing. - On the Mac, the Simulator and iPhone drivers need Xcode 26 or 27, selected with
xcode-select, with an iOS Simulator runtime (Supported platforms); the Mac's binaries are built on GitHub'sxcode-27image, with its Xcode 27, and the daemon carries the Simulator reader and the Android agent. A physical iPhone also needs the runner, built and signed for a development team from a checkout of the same version and named by an absolute path inMOBILE_AGENT_IOS_RUNNER_APP(Quick start;agent-ios/README.md). Android needs the SDK'splatform-tools(Quick start). - Linux hosts drive Android only: the Simulator and iPhone drivers are stubs there (Supported platforms).
crates.io. cargo install mobile-agent@0.1.0-alpha.1 mobile-agent-daemon@0.1.0-alpha.1 mobile-agent-mcp@0.1.0-alpha.1 builds the three from their packages, each version named, since Cargo picks a pre-release only when its version is named; the packages lack the Android agent, the Simulator reader and the checkout's libjpeg-turbo settings (Crates).
Build
The alternative to Install: the three binaries built from a checkout, for main between alphas, a change of your own or a target the releases do not carry.
Requirements:
- Rust. Install rustup. It takes the toolchain from
rust-toolchain.toml: the version pinned there, with clippy, rustfmt and theaarch64-apple-ios-simtarget. Runrustup toolchain installin the checkout, as CI does, to install them before the first build, or when cargo reports that the pinned toolchain is not installed;rustup show active-toolchainthere names the toolchain in use. - macOS, for the Simulator. Xcode 26 or 27, selected with
xcode-select, with an iOS Simulator runtime; and libjpeg-turbo,brew install jpeg-turbo, which the frame encoder links statically from Homebrew's Apple silicon prefix (.cargo/config.toml; setTURBOJPEG_LIB_DIRandTURBOJPEG_INCLUDE_DIRfor another prefix). - The Android agent. The daemon's build compiles the agent with
agent-android/build.sh(kotlinc and R8, no Gradle) and embeds the jar, so it needs a JDK 17 or newer withjavaandjaronPATH(tested with Temurin 21), the Kotlin compiler,kotlinconPATHorKOTLIN_HOMEset to the compiler's home, the directory holdingbin/kotlincandlib/(tested with 2.4.20), and an Android SDK atANDROID_HOME, by default$HOME/Library/Android/sdk, withplatforms;android-36and abuild-toolspackage (CI installs 37.0.0). On Linux, setANDROID_HOME. - Android at run time. The SDK's
platform-tools, whose adb server the driver talks to on port 5037, and for an emulator, theemulatorpackage and an AVD. - The iPhone's runner.
agent-ios/build.sh, whichjust agent-ios-buildruns, builds the runner foraarch64-apple-ios, the second targetrust-toolchain.tomlnames, links it into a copy of Xcode'sXCTRunner.appwith the iPhoneOS SDK'sclangand signs it withcodesignfor the teamMOBILE_AGENT_IOS_TEAMnames, with noxcodebuildproject, into the git-ignoredagent-ios/dist/(agent-ios/README.md, Building and signing). It needs Xcode 27.0's iPhoneOS SDK, the only one tried, and the team's identity and profile (Quick start). The daemon installs that bundle from the workspace it was built in, or the oneMOBILE_AGENT_IOS_RUNNER_APPnames, when the phone's runner is missing or says hello with another version (crates/daemon/README.md, The physical iPhone driver).
From the checkout:
cargo build --release # target/release/mobile-agent, mobile-agent-daemon and mobile-agent-mcp
export PATH="$PWD/target/release:$PATH" # the CLI starts the daemon it finds beside itself
cargo build --profile profilingbuilds the release code with line-level debug information and nothing stripped, intotarget/profiling/, for a sampling profiler such as Instruments' Time Profiler, which then names inlined functions and lines; release builds strip the debug information (spike S15,docs/spikes/s15-profiles.md).SKIP_AGENT_BUILD=1 cargo build --releasebuilds without the Android toolchain. That daemon deploys an agent only from a jar thatMOBILE_AGENT_JARnames at run time;MOBILE_AGENT_JARset at build time embeds that jar instead of building one.- The Simulator's tree reader is cross-compiled for
aarch64-apple-ios-simduring the build and embedded in the daemon, behind thereaderfeature ofcrates/simulator, which is on by default. The daemon spawns it into each booted Simulator it attaches. Without that Rust target the build warns and embeds no reader, and tree reads fall back to the slower host translator, marked degraded;doctorshows which one a build has. - Contributors: every dependency install goes through Socket Firewall. Install it with
npm i -g sfw, then prefix installs with it:sfw cargo fetch,sfw cargo add,sfw cargo install just,sfw npm install -g @fission-ai/openspec.just validateruns the checks a change must pass: build, clippy with warnings denied, format check, the publish scan (just check-public: no machine path, device identifier, team id, email, host model or private term in a tracked file, and gitleaks' rules when it is installed), the workflows' lint and audit (actionlint and zizmor, when installed), the dependencies' check (cargo deny, when installed), tests, the checks of the repository's own scripts, the agent build, the iPhone runner's build, the Kotlin codec cross-check, the fixture scripts' checks with fake build tools, the fixture builds (with the SwiftUI and Expo fixtures' device builds whenMOBILE_AGENT_IOS_TEAMis set) andopenspec validate. The tests that need a Simulator, an emulator or an iPhone skip unless their environment names one (crates/daemon/README.md,crates/simulator/README.md,crates/ios/README.md).
Crates
The workspace's packages carry the names they have on crates.io, where 0.1.0-alpha.1 is the first version and the release workflow publishes the next ones after their release; each library keeps the short name the code imports, and each binary its name.
| Package | Directory | Library | What it holds |
|---|---|---|---|
mobile-agent |
crates/cli |
cli |
the CLI, binary mobile-agent |
mobile-agent-daemon |
crates/daemon |
daemon |
the daemon, binary mobile-agent-daemon |
mobile-agent-mcp |
crates/mcp |
none | the MCP server, binary mobile-agent-mcp |
mobile-agent-wire |
crates/wire |
wire |
the daemon's requests and replies as types |
mobile-agent-protocol |
crates/protocol |
protocol |
the device protocol between the daemon and the device agents |
mobile-agent-mirror |
crates/mirror |
mirror |
the live UI replica of a target |
mobile-agent-android |
crates/android |
android |
the Android driver |
mobile-agent-simulator |
crates/simulator |
simulator |
the iOS Simulator driver |
mobile-agent-simulator-reader |
crates/simulator/reader |
simulator_reader |
the Simulator's tree reader, binary simulator-reader, and the tree conversion the iPhone's runner shares |
mobile-agent-ios |
crates/ios |
ios |
the physical iPhone driver |
mobile-agent-ios-runner |
agent-ios |
agent_ios |
the iPhone runner's agent, which agent-ios/build.sh links into the signed runner |
mobile-agent-bench |
crates/bench |
bench |
the benchmark harness, binary mobile-agent-bench; never published (publish = false), since it runs in a checkout |
A build of the packages, as cargo install mobile-agent-daemon makes from crates.io, has three differences from a checkout's: the daemon embeds no Android agent, whose sources are outside its package, and deploys one only from the jar MOBILE_AGENT_JAR names; the Simulator driver embeds no tree reader, a package of its own, and reads trees through the host translator unless MOBILE_AGENT_READER names a reader built in a checkout; and on macOS libjpeg-turbo is found only where TURBOJPEG_LIB_DIR and TURBOJPEG_INCLUDE_DIR name it, since .cargo/config.toml is the checkout's (crates/simulator/README.md, From the crate's package; crates/daemon/README.md). Every release daemon embeds the agent, and the Mac's also the reader and libjpeg-turbo (Install).
mobile-agent MCP questions
What platforms does mobile-agent support?
It supports Android devices and emulators, as well as iOS Simulators and physical iPhones.
Can I use mobile-agent on Linux?
On Linux, it only supports the Android driver; the Simulator and iPhone drivers are built as stubs.
Does mobile-agent require installing an APK on Android?
No, it uses a single-dex agent pushed over adb that runs as the shell user, so no APK is installed and no instrumentation is required.