podium-mcp

podium-mcp is an MCP (Model Context Protocol) server designed to provide AI agents with automation capabilities for mobile and canvas UI. It exposes 51 tools through a single stdio endpoint, replacing the approach that usually requires configuring multiple MCP servers.

Purpose

podium-mcp is mainly used for end-to-end testing, UI automation, debugging, and assertion verification of iOS and Android apps on macOS. It is especially aimed at React Native apps and WebView-based hybrid apps, as well as games or graphical interfaces that use Canvas/WebGL.

Main capabilities

• Device and app management: Unified management of iOS simulators (simctl), physical iPhones (devicectl), and Android devices (adb), distinguished by platform-tagged device models.
• Native UI inspection and gestures: Routes gestures through idb / mobilecli, with Maestro as a fallback, avoiding starting a JVM for every gesture.
• End-to-end flows and batch automation: Supports declarative Maestro flows, ordered action batches, and flow export from engineers to QA.
• Trustworthy assertions: Uses an "oracle ladder" (WebView-DOM › native accessibility › Maestro) to return falsifiable, evidence-backed verdicts, and fails closed when verification is impossible.
• WebView DOM and network: Parses the WKWebView DOM to obtain tap coordinates, execute JS, drive navigation, and capture in-page HTTP traffic in JSON/HAR format.
• React Native debugging: Obtains Metro console logs, network requests, and in-app state via CDP, as well as host/simulator crash reports.
• Physical device support: Android emulators/devices via adb (gestures + uiautomator hierarchy); real iOS via devicectl lifecycle and an optional WebDriverAgent backend.
• Canvas and game engine automation (no vision): The Canvas/WebGL brain drives Pixi/Konva/Fabric/Phaser/Three/Babylon UI as addressable objects (verified live in WebKit). Experimental engine bridges can drive Unity/GL through AltTester instrumented builds (or the window.__podiumEngine WebGL bridge); the code is complete and passes simulated tests, but has not yet been run on a real Unity build.

Usage

Requirements

• macOS with Xcode command line tools installed (xcrun, simctl)
• Node.js ≥ 22 (uses native fetch and WebSocket; .npmrc sets engine-strict=true)
• mobilecli (automatically bundled as an npm dependency, default native gestures + WebView backend, no separate installation required)
• Optional: idb (idb + idb_companion) — the preferred native gesture backend when both are present, automatically detected
• Optional: Maestro in PATH (or located at ~/.maestro/bin) — the run_flow engine and gesture fallback path
• Optional: a running Metro bundler, for metro_* debugging tools
• Optional: Android SDK + adb — adb path detection only, gracefully degrades when missing

Installation

• Claude Code plugin (recommended): Install after a one-time marketplace setup; the plugin automatically starts the MCP server (all 51 tools) and comes with five skills.
• npx (zero install): Ready to use directly.
• Manual (from source): After building the server, register it with any MCP client. Claude Code uses the .mcp.json configuration.

Quick start (order of use)

1. podium_health — confirm xcrun / maestro / native backend availability.
2. device_list — select a booted simulator udid.
3. Read state — app_list, app_state, screen_size, orientation_get.
4. Drive the device — app_launch, then tap_on / input_text / swipe / press_key, as well as set_location and orientation_set. Execute in batch with run_steps.
5. Authoring and verification — inspect_screen discovers elements, run_flow performs declarative checks, then assert_visible / validate_flow yields evidence-backed verdicts.
6. Inspecting WebView — webview_inspect → tap coordinates, webview_eval, webview_navigate, webview_network.
7. Capture and debugging — screenshot / record_start → record_stop; metro_logs / metro_network / metro_state; crash_list / crash_get.

Every tool returns structured JSON and never throws — failures are returned as MCP tool errors.

When to use

• End-to-end mobile app testing on iOS simulators, physical iPhones, and Android devices on macOS.
• Debugging React Native apps, including Metro logs, network requests, and state inspection.
• DOM and network inspection of hybrid apps (WebView-hosted UI).
• Automation of Canvas/WebGL apps using frameworks such as Pixi, Konva, Fabric, Phaser, Three, Babylon.
• QA flows that require trustworthy assertions and evidence.

Limitations

• Canvas/WebGL requires a cooperating JS framework: the Canvas brain automates Pixi/Konva/Fabric/Phaser/Three/Babylon UI via selectors, provided the app exposes a scene graph root (verified). Raw/custom WebGL canvases, opaque/production builds, or Unity without an AltTester / window.__podiumEngine bridge cannot be addressed via selectors — fall back to tap_with_fallback using screenshot coordinates, or instrument the build.
• WebView tools are dev/QA only: production App Store builds usually set isInspectable = false; the tools return an actionable error and fall back to coordinate taps.
• WebView content process memory cannot be read from the app sandbox (platform limitation) — use indirect signals (memory warnings, process termination).
• Maestro text matchers: are full-string regex (IGNORE_CASE) — partial strings do not match; copy the hierarchy text verbatim or anchor with .*.
• Android requires adb on PATH: once adb is present, gestures/inspection/screenshots work; when missing, all Android paths degrade to a structured "adb not found" result.
• orientation_get is a screenshot aspect-ratio heuristic when there is no native backend: iOS simulators do not expose a direct orientation query.
• record_start / record_stop keep state in-process: start → … → stop must be serialized on the same connection; one active recording per udid (a watchdog finalizes recordings that are never stopped).
• Game engine tools are experimental: the AltTester path has not yet been verified on real Unity builds; Unity-WebGL requires the app to expose window.__podiumEngine. Engine tools require an AltTester-instrumented build (dev/staging) or that WebGL bridge; on non-instrumented builds they fail closed with an actionable error — never falling back to vision.

Platform scope (v0.3.0)

podium automates iOS simulators, physical iPhones (devicectl lifecycle + optional WebDriverAgent), and Android emulators/devices (adb gestures + uiautomator hierarchy). device_list marks the platform for each target, and the backend is selected per target. When a toolchain (such as adb) is missing, these paths degrade to informational results rather than failures.