pymobile-mcp

Pure Python MCP server for mobile automation.

• Android: uiautomator2 + adbutils
• iOS: pure pymobiledevice3 userspace tunnel + WebDriverAgent (no go-ios, no root)

Public contract: fixed upstream mobile-mcp@c5d7d27 — 23 tools by default, 26 with MOBILEFLEET_ENABLE=1. mobile_get_page_source is not public; fleet runtime uses the documented approved exception when no Python fleet provider is installed.

Current release: 0.3.1 · Changelog · Live regression checklist

Features

• One stdio MCP server for Android + iOS
• Upstream-compatible natural-language/image results and exact Actionable vs isError=true failures
• Live smoke scripts that exit blocked (code 2) when devices are missing — never fake pass
• Destructive actions (install/uninstall) gated by explicit env flags

Requirements

Install

From a git checkout (development)

git clone https://github.com/ByteTrue/pymobile-mcp.git
cd pymobile-mcp
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
pymobile-mcp --help

Dev install (tests)

pip install -e ".[dev]"
python -m pytest -q

From PyPI

pip install pymobile-mcp==0.3.1

From GitHub (no local clone of tooling)

pip install "git+https://github.com/ByteTrue/pymobile-mcp.git@v0.3.1"

Quick start

1. Connect an Android emulator/device (adb devices) and/or a paired iPhone.
2. For iOS, ensure your WDA runner is installed (Xcode once); pymobile-mcp launches it over userspace tunnel.
3. Run the server:

pymobile-mcp run
# equivalent:
python -m pymobile_mcp.cli run

4. Point an MCP client at the process (stdio).

MCP client config

Installed entrypoint (pymobile-mcp on PATH):

{
  "mcpServers": {
    "pymobile-mcp": {
      "command": "pymobile-mcp",
      "args": ["run"]
    }
  }
}

Checkout / venv (absolute paths are more reliable for GUI clients):

{
  "mcpServers": {
    "pymobile-mcp": {
      "command": "/ABS/PATH/pymobile-mcp/.venv/bin/python",
      "args": ["-m", "pymobile_mcp.cli", "run"],
      "cwd": "/ABS/PATH/pymobile-mcp",
      "env": {
        "NO_PROXY": "*",
        "PYTHONPATH": "src"
      }
    }
  }
}

First tools to try

After the client connects:

1. mobile_list_available_devices — confirm Android/iOS ids
2. mobile_get_screen_size / mobile_take_screenshot
3. mobile_list_elements_on_screen — UI tree (no raw page source tool)
4. mobile_list_apps → mobile_launch_app with a known package/bundle id

Capability matrix (23 default tools; 26 with fleet env)

Current live evidence passes on Android physical, Android emulator, iOS Simulator, and iOS real device. Android recording and iOS Simulator recording both passed live; iOS real-device recording remains the approved exception.

Environment variables

Live smoke

Scripts print JSON with status: passed|failed|blocked.
Exit 2 + blocked = missing device/env, not a product pass.

export NO_PROXY='*'
PATH=.venv/bin:$PATH

# Android
python tests/android_live_smoke.py
PYMOBILE_MCP_ANDROID_ACTIONS=1 python tests/android_live_smoke.py
python tests/android_app_system_live_smoke.py
python tests/android_recording_crash_live_smoke.py

# iOS (unlock phone for open_url)
python tests/ios_pmd3_wda_live_smoke.py
PYMOBILE_MCP_IOS_ACTIONS=1 python tests/ios_pmd3_wda_live_smoke.py
python tests/ios_system_helpers_live_smoke.py
python tests/ios_app_lifecycle_live_smoke.py
python tests/crash_tools_live_smoke.py
python tests/ios_app_recording_crash_live_smoke.py   # real recording uses approved exception

Full dual-device gate: docs/regression-checklist.md.

Architecture (short)

MCP client  --stdio-->  pymobile-mcp server
                           │
                           ├─ tools/registry + specs   (23 default / 26 fleet contract)
                           ├─ tools/* handlers
                           └─ drivers/
                                ├─ android.py       (adbutils / uiautomator2)
                                ├─ ios.py           (UserspaceRsdTunnel + WDA)
                                └─ ios_simulator.py (simctl + WDA)

Development

pip install -e ".[dev]"
python -m pytest -q

CI runs unit tests on Python 3.11 and 3.12 (workflow). Device live smokes stay local.

Known limits

• Android crashes come from dumpsys dropbox --print, filtered to crash/ANR/tombstone-like tags by default
• iOS real-device recording remains an approved exception; Simulator recording requires a booted CoreSimulator + WDA
• Recording state is process-local (ActiveRecording); no cross-process resume
• Custom URL schemes need MOBILEMCP_ALLOW_UNSAFE_URLS=1
• Screenshot/recording host paths must resolve under cwd or system temp
• No go-ios/mobilecli runtime fallback by design

Troubleshooting