Mobile Automator MCP Server

An MCP server that gives AI agents the power to record, replay, and mock mobile app interactions — combining Maestro UI automation with Proxyman network capture to generate complete, self-contained test scripts.

Architecture

The system orchestrates two async data streams — UI interactions (via Maestro) and HTTP traffic (via Proxyman) — then correlates them by timestamp to produce Maestro YAML + WireMock stubs for full experience replay.

Related MCP server: Mobile Device MCP

Capabilities

Tools

Quick Start

Prerequisites

• Node.js v20+

• Maestro CLI 2.5.0+ — curl -Ls "https://get.maestro.mobile.dev" | bash (older versions log a warning at startup; 2.3.x in particular exhibits XCTest driver flakiness on iOS port 22087)

• Proxyman macOS 5.20+ with CLI — see Proxyman Setup

• A booted iOS Simulator or Android Emulator

Install

git clone <repository>
cd mobile-automator-mcp
npm install
npm run build

Option A — HTTP Bridge (use this if the MCP client is blocked at your org)

npm run dev:http

Verify it's running:

curl http://localhost:3000/health
# {"ok":true,"tools":34}

Then call any tool via JSON-RPC:

curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices","arguments":{"platform":"ios"}}}'

For a full tool reference, session lifecycle patterns, and common workflows see .github/skills/generate_mcp_curls/SKILL.md.
To regenerate boilerplate curl commands for all 34 tools: npx tsx .github/skills/generate_mcp_curls/generate.ts

Phase-1 admin tools

When something looks stuck, five admin tools provide visibility and recovery without restarting the server:

• audit_state — single-shot snapshot of sessions, drivers, pollers, and Proxyman rules with an orphans report

• list_active_sessions — read-only inventory with driver/poller liveness and mock counts

• list_active_mocks — Proxyman rules tagged mca: plus drift between Proxyman and the local ledger

• force_cleanup_session — destructive: stop poller/driver, delete tagged Proxyman rules, mark session aborted (never throws)

• force_cleanup_mocks — destructive bulk delete of mca:-tagged Proxyman rules by scope (all, session, standalone)

Option B — Register with an MCP Client (once org-approved)

Add to your MCP client config (e.g., Claude Desktop, Gemini Code Assist):

{
  "mcpServers": {
    "mobile-automator": {
      "command": "node",
      "args": ["/absolute/path/to/mobile-automator-mcp/dist/index.js"]
    }
  }
}

Selective Mocking

The stop_and_compile_test tool accepts a mockingConfig to control which APIs are mocked vs. proxied to a real backend:

full      → Mock all captured APIs (default, no real server needed)
include   → Mock only listed routes, proxy everything else
exclude   → Mock everything EXCEPT listed routes

Example — mock only login, proxy everything else:

{
  "mockingConfig": {
    "mode": "include",
    "routes": ["/api/login"],
    "proxyBaseUrl": "http://localhost:3030"
  }
}

Output Structure

session-<id>/
├── wiremock/
│   ├── mappings/           ← WireMock stub JSON files
│   │   ├── post_api_login.json
│   │   ├── get_api_lore_doom.json
│   │   └── _proxy_fallback.json   ← (include/exclude modes only)
│   └── __files/            ← Response body fixtures
│       ├── post_api_login_response.json
│       └── get_api_lore_doom_response.json
└── manifest.json           ← Session metadata + route manifest

Project Structure

src/
├── index.ts              ← MCP server entry point
├── handlers.ts           ← Tool handler implementations
├── schemas.ts            ← Zod schemas (single source of truth for I/O)
├── types.ts              ← Domain models
├── session/              ← Session lifecycle + SQLite persistence
├── maestro/              ← Maestro CLI wrapper + hierarchy parser
├── proxyman/             ← Proxyman CLI wrapper + payload validator
├── flows/                ← Named, hand-authored flow registry
├── build/                ← iOS (xcodebuild/simctl) + Android (gradlew/adb) build & deploy
├── screenshot/           ← PNG capture for visual self-verification
├── testing/              ← XCTest / JUnit unit-test runner + result parsers
└── synthesis/            ← Correlator + YAML generator + WireMock stub writer

Named Flows

Hand-authored Maestro flows let an agent navigate to a specific app screen before verifying an incremental change. Flows live as .yaml files in a flows directory (default: ./flows/) and are invoked by name.

flows/
├── _manifest.json              ← optional: descriptions, tags, param specs
├── login.yaml                  ← flow name is "login"
└── navigate-to-checkout.yaml   ← flow name is "navigate-to-checkout"

An optional _manifest.json declares parameters and metadata:

{
  "flows": {
    "login": {
      "description": "Launch the app and reach the logged-in home screen",
      "tags": ["auth", "setup"],
      "params": {
        "USERNAME": { "default": "admin", "description": "Login username" },
        "PASSWORD": { "default": "admin" }
      }
    }
  }
}

Params are forwarded to Maestro as -e KEY=VALUE and referenced inside the YAML as ${KEY}. Call list_flows to discover flows, then run_flow with { name, params? } to execute one.

Build & Deploy Loop

Closes the edit → rebuild → reinstall → navigate cycle so an agent can verify changes against a fresh build.

build_app     → compile with xcodebuild / ./gradlew, return built .app or .apk path
uninstall_app → wipe the prior install + its data from the target device
install_app   → push the new binary to the simulator / emulator
boot_simulator→ boot an iOS simulator (idempotent; alreadyBooted=true if already running)

iOS — shells xcodebuild build -scheme <scheme> -destination 'generic/platform=iOS Simulator' -derivedDataPath <path> and locates the .app under <derivedDataPath>/Build/Products/<Configuration>-iphonesimulator/. Bundle id is extracted via plutil from the built Info.plist.

Android — shells ./gradlew :<module>:assemble<Variant> from the project root and locates the APK at <project>/<module>/build/outputs/apk/<variant>/. Booting the emulator is not yet automated — start it manually (e.g., emulator -avd <name>) before calling install/run tools.

Build output is truncated (head + tail) to keep MCP responses small while preserving both the lead-up and the final error context.

Visual Verification & Unit Tests

take_screenshot writes a PNG to disk and returns its path — Claude reads the image back directly, which catches visual regressions (wrong color, clipped text, broken image) that structural hierarchy checks miss. Pair it with get_ui_hierarchy for structural assertions.

run_unit_tests runs the normal unit-test target for the project:

• iOS — xcodebuild test -resultBundlePath <path> with optional -only-testing:<Target>/<Class>[/<Method>] filters. The stdout is parsed for per-test pass/fail so totals stay accurate across Xcode versions.

• Android — ./gradlew :<module>:test<Variant>UnitTest with an optional --tests <filter>. JUnit XML under <module>/build/test-results/<task>/ is parsed for failure details.

Both return structured results: { passed, totalTests, passedTests, failedTests, skippedTests, failures[] }. failures[] carries the failing test name and (where available) the first-line error message plus source file/line — enough for the agent to jump straight to the offending code without grepping the full log.

The full agent workflow (build → install → navigate → screenshot → unit test → iterate) is documented in .agents/skills/agent-loop.md.

Development

npm test            # Run tests
npm run test:watch  # Watch mode
npm run build       # Compile TypeScript
npm start           # Start server (stdio)
npm run lint        # ESLint

License

MIT