mobile-agent-mcp

MCP + CLI for iOS sims, Android emulators, and USB devices. Maestro runs flows; this handles config, doctor, logs, screenshots, RN diagnosis, and Expo/Android host plumbing.

Quick start

npm install -D mobile-agent-mcp
mobile-agent doctor
mobile-agent run-with-context smoke-login ios --json

Requires Node 20+, Maestro, Xcode (iOS), adb (Android).

Config

mobile-agent.config.json in repo root. See mobile-agent.config.example.json, examples/expo.config.json, examples/bare-rn.config.json.

Set MOBILE_AGENT_PROJECT_ROOT if MCP starts from the wrong cwd.

MCP tools

| Tool | Purpose | |------|---------| | doctor | Preflight checks | | run_flow_with_context | Flow + logs + screenshot + diagnosis | | run_maestro_flow / run_smoke_flows | Flow execution | | screenshot | PNG + inline image | | collect_logs / tail_logs | Metro, logcat, sim logs | | metro_status / reload_app / boot_simulator | Dev lifecycle | | validate_flow / write_flow | Flow authoring | | adb_reverse / open_url / open_dev_url | RN/Expo plumbing |

Resource: mobile-agent://screenshot/latest

Responses: docs/mcp-response-schema.md. Agent loop: docs/agent-skill.md.

MCP config:

{
  "mcpServers": {
    "mobile-agent": {
      "command": "npx",
      "args": ["-y", "mobile-agent-mcp"],
      "env": { "MOBILE_AGENT_PROJECT_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

CLI

mobile-agent doctor [--json]
mobile-agent run-with-context <flow> [ios|android] [--json]
mobile-agent run-all [ios|android] [--json]
mobile-agent logs [ios|android] [--json] [--duration-ms 3000]
mobile-agent screenshot [ios|android] [--json]
mobile-agent metro-status | reload-app | boot-simulator [--json]
mobile-agent validate-flow <flow> | write-flow <flow> [--template smoke] [--json]
mobile-agent adb-reverse 8081
mobile-agent open-dev-url [ios|android]

Flags: --project-root, --flows-dir, --screenshot-dir.