Mobile MCP Server for iOS and Android Automation

Overview

Mobile MCP Server is a lightweight server that exposes a consistent HTTP/WebSocket API for automating, scraping, and controlling iOS and Android devices — both physical hardware and simulators/emulators. It is designed as a central bridge between test frameworks or automation clients and platform-specific tooling (ADB, simctl, XCTest/WebDriverAgent), providing a unified, scriptable interface for device management, UI hierarchy inspection, input injection, screenshots, and app lifecycle actions.

This server is useful when you need to run cross-platform mobile tests, collect UI metadata at scale, orchestrate device fleets, or drive manual/automated interactions from remote clients. By centralizing device-facing operations behind a protocol-compatible server, teams can build reproducible automation pipelines, attach different frontends or AI agents, and integrate with CI/CD systems without dealing with platform differences directly.

Features

• Unified API for iOS and Android devices (physical and simulators/emulators)
• Device discovery and metadata (model, OS version, status)
• App management: install, uninstall, launch, terminate, and query installed packages
• UI inspection and scraping: hierarchical view dumps and element attributes
• Input injection: tap, swipe, text entry, key events
• Screenshots and screen recording endpoints
• Session and concurrency management for parallel testing
• File transfer to/from device (push/pull)
• Logging, telemetry, and basic access control (token authentication)
• Works with ADB, simctl, XCTest/WebDriverAgent (platform adapters)

Installation / Configuration

Clone the repository and run with Docker (recommended for quick start):

# Clone the repo
git clone https://github.com/mobile-next/mobile-mcp.git
cd mobile-mcp

# Run the official Docker image
docker run -d \
  -p 8765:8765 \
  -e MCP_AUTH_TOKEN="replace-with-token" \
  --privileged \          # required for access to USB devices / adb over USB
  --name mobile-mcp \
  mobile-next/mobile-mcp:latest

Run from source (example workflow — exact build steps depend on language/runtime):

# After cloning
cd mobile-mcp

# Install dependencies (node/python/go as applicable)
# for Node:
npm install

# Build / start
npm run build
npm start -- --port 8765 --auth-token "replace-with-token"

Important environment variables and configuration options:

• MCP_PORT (default: 8765) — HTTP port to listen on
• MCP_AUTH_TOKEN — simple bearer token for API access
• ANDROID_SDK_ROOT — path to Android SDK (required for ADB/emulator)
• XCODE_DEVELOPER_DIR — path to Xcode tools when interacting with iOS
• DEVICE_CONCURRENCY — max simultaneous sessions per server
• LOG_LEVEL — debug/info/warn/error

Platform prerequisites:

• Android: Android SDK, ADB on PATH; enable USB debugging on devices
• iOS: Xcode + command line tools; proper device provisioning for physical devices; simctl for simulators

Available Resources

The server exposes a set of HTTP and WebSocket endpoints for automation clients. Common resource endpoints include:

Client libraries or example scripts (in the repository) demonstrate how to call these endpoints from Node/Python/CLI. Use the GitHub repo for code samples and OpenAPI/JSON schema (if provided).

GitHub: https://github.com/mobile-next/mobile-mcp

Use Cases

1. End-to-end testing across platforms

   • Start multiple sessions against different devices, run deterministic UI actions, and assert results. Example:

   # create a session (pseudo-curl)
   curl -X POST "http://localhost:8765/sessions" \
     -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"deviceId":"device-serial-1","capabilities":{"app":"com.example.app"}}'
   

2. App scraping for QA and accessibility

   • Obtain a UI hierarchy dump to analyze element labels, accessibility ids, and properties for automated accessibility checks:

   curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
     "http://localhost:8765/ui/hierarchy?deviceId=device-serial-1&format=json" > ui-tree.json
   

3. Visual regression and screenshots

   • Capture screenshots from multiple device configurations and compare against gold images:

   curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
     "http://localhost:8765/screenshot?deviceId=device-serial-1" --output snapshot.png
   

4. Device farm orchestration

   • Combine MCP instances to manage a pool of devices. Use /devices to balance tests, install apps remotely, and collect logs for CI failure triage.

5. Remote debugging and replay

   • Record interaction sequences from a client