🎙️ podium-mcp

One baton. Every instrument.

A single stdio endpoint with 33 tools for iOS-simulator device control, native UI automation, end-to-end flows, React Native debugging, and WebView DOM inspection — one connection instead of several.

_{One prompt → podium drives Safari live → types the URL → explores the profile → opens a repo. Footage captured on a live iPhone 16 Pro simulator.}

A podium is where a maestro stands — one place to conduct the whole orchestra. This MCP server unifies three capability sets into a single stdio endpoint: device management (via simctl, with graceful adb support), UI inspection, interaction, and declarative end-to-end flows (driven through the Maestro flow engine), and React Native debugging (Metro console logs over CDP + crash reports). Rather than wiring several separate MCP servers into every client config, podium-mcp exposes everything behind one connection, with a shared exec layer, consistent error handling, and a single health-check tool to confirm what toolchain is available on the host machine.

• Why
• Requirements
• Installation
• Usage
• Prompt playbook
• Capability coverage
• Tool reference
• Documented limits
• Architecture
• Development
• Full tool catalog
• Verified end-to-end
• Design ideas
• Contributing
• Security
• License

Driving a React Native app end-to-end usually means juggling three MCP servers — one for device/app control, one for UI flows, one for Metro/debugger logs — each with its own config entry, its own quirks, and its own failure modes. podium-mcp collapses that into one server with:

• a single execFile-based command runner (no shell — arguments are passed verbatim),
• consistent structured errors (a tool never crashes the server),
• automatic retry around Maestro's known iOS-driver flakiness,
• graceful degradation when a toolchain (e.g. adb) is absent.

• macOS with Xcode command-line tools (xcrun, simctl)
• Node.js ≥ 22 (uses native fetch and WebSocket)
• mobilecli — bundled automatically as an npm dependency; the default native gesture + WebView backend (no separate install)
• (optional) idb (idb + idb_companion) — preferred native gesture backend when both are present; auto-detected
• (optional) Maestro on PATH (or at ~/.maestro/bin) — the run_flow engine and the gesture fallback path
• (optional) Android SDK + adb — adb paths degrade gracefully when absent
• (optional) a running Metro bundler for the metro_* debugging tools

Install podium-mcp as a Claude Code plugin — no manual config needed. One-time marketplace setup, then install:

/plugin marketplace add github:hoainho/podium-mcp
/plugin install podium-mcp@podium

Once installed, four skills are available directly in Claude Code:

The plugin auto-starts the MCP server (all 33 tools) when enabled. No .mcp.json edits required.

To submit this plugin to the Claude community marketplace (for discovery without the marketplace add step): claude.ai/settings/plugins/submit

git clone git@github.com:hoainho/podium-mcp.git
cd podium-mcp
npm install
npm run build

Register the built server with any MCP client. Claude Code (.mcp.json):

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

Quick manual smoke test over raw stdio (lists the registered tools):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node dist/index.js

Then call podium_health first to confirm which toolchain is available on the host.

Copy-paste prompts for common React Native testing & debugging tasks — e2e flows, test cases, feature verification, bug fixing, and device control — live in prompts/. Each prompt names the podium tools it drives and was validated against a real simulator. Start with prompts/README.md.

WebView tools (webview_inspect/eval/navigate) use the bundled mobilecli over CDP — not the idb or Maestro paths — and require the app's WKWebView.isInspectable = true (default in debug/staging builds; usually disabled in production App Store builds).

Imperative gestures (tap_on, input_text, swipe, press_key, orientation_set) and inspect_screen route through the fastest available backend, probed once and cached:

1. idb — used when both idb and idb_companion are installed (native, fastest).
2. mobilecli — the bundled npm dependency (prebuilt Go binary). Default backend; no install needed.
3. Maestro fallback — when no native backend resolves, or for actions a native backend can't express (double/long-press, UPSIDE_DOWN). The gesture generates a minimal flow with launchApp: { stopApp: false }, foregrounding the app without restarting so state is preserved.

Each result reports the backend it used. Set PODIUM_DISABLE_NATIVE=1 to force the Maestro path. Eliminating the per-gesture JVM spin-up cut tap_on from ~14.7 s to ~0.6 s and inspect_screen from ~8.9 s to ~0.9 s on an iPhone 16 Pro simulator. Run npm run benchmark for a full 33-tool pass/fail sweep.

When the Maestro fallback path runs, its iOS driver intermittently fails with Failed to connect to 127.0.0.1:<port> / java.net.ConnectException. Flow executions automatically retry up to 2 times with 2s / 5s backoff and report the retries count. If it persists, the structured failure includes the raw output — the usual remedies are rebooting the simulator (device_boot after shutdown) or restarting the Maestro daemon.

• WebGL/Canvas content is un-automatable by selector — no DOM/hierarchy; use tap_with_fallback with screenshot-derived coordinates.
• inspect_screen sees only the native layer for WebView content — use webview_inspect to resolve WKWebView DOM elements to tap coordinates (requires isInspectable = true).
• WebView tools are dev/QA only — production App Store builds typically set WKWebView.isInspectable = false.
• No Android SDK assumption — every adb-backed path degrades to a structured "adb not found" result instead of failing.
• WebView content-process memory is unreadable from the app sandbox (iOS/Android platform limit) — use indirect signals (memory warnings, process terminations).
• Maestro text: matcher is full-string regex (IGNORE_CASE) — partial strings don't match; copy hierarchy text verbatim or anchor with .*.
• record_start/record_stop keep recorder state in-process (one Map per udid, server is long-lived). Clients must serialize start → … → stop on the same connection; firing both in one un-awaited batch races. One active recording per udid.

src/
  index.ts          # MCP server entry — registers every tool group, warms caches
  lib/
    exec.ts         # execFile-based command runner (NO shell) + commandExists
    result.ts       # shared ok/error MCP content helpers
    simctl.ts       # xcrun simctl wrappers + device-list TTL cache
    native.ts       # gesture/inspect backend abstraction: idb → mobilecli → null
    idb.ts          # idb gesture/inspect adapter
    gesture.ts      # nativeTap hybrid (backend → Maestro fallback)
    maestro.ts      # Maestro engine: flow runner, idb retry, hierarchy
    webview.ts      # mobilecli CDP — WebView list/inspect/eval/navigate
    metro.ts        # Metro CDP — app discovery + console log capture
    crash.ts        # DiagnosticReports crash listing/reading
    recording.ts    # detached screen recording lifecycle
  tools/            # one file per group (health, device, screen, flow, debug, webview)
assets/             # bundled offline Maestro cheat sheet
scripts/            # benchmark.ts (33-tool e2e), compare-mcps.ts
docs/               # tool catalog + e2e transcript

npm run build       # tsc
npm run typecheck   # tsc --noEmit
npm test            # vitest run (61 tests; exec/network layer mocked — no sim needed)

Standards: TypeScript strict, no as any / @ts-ignore, no shell execution (all commands via lib/exec.ts), tools return structured errors instead of throwing. See CONTRIBUTING.md for the full guide and the "add a new tool" checklist.

See docs/tool-catalog.md for the authoritative tool-by-tool reference — every tool with its parameters, backing engine, and fallback behavior, plus the items deferred to a future version (cloud execution, live viewer).

See docs/e2e-demo.md for a real transcript against a booted iPhone 16 Pro simulator running a production React Native app.

Platform note: macOS + iOS Simulator is the primary target. Android degrades gracefully — tools check for adb at runtime and return informative errors when the Android SDK is absent rather than failing hard.

podium-mcp is built around a few deliberate principles:

• One podium, one connection. A single server fronts every mobile capability — device, UI, flows, capture, debugging, and WebView inspection — so an agent configures one endpoint and discovers all 33 tools at once, instead of stitching together several servers.
• Safe by construction. Every external command runs through an execFile layer with an explicit argument array — never a shell string — so tool inputs (udids, paths, selectors, flow YAML) can't be interpreted as commands.
• Never crash the conductor. Tools return structured results and errors instead of throwing; one bad call can't take the server down.
• Degrade, don't fail. A missing toolchain (e.g. Android's adb) yields an informative result rather than a hard error.
• Resilient automation. Flaky simulator drivers are retried with backoff, and every result reports exactly what happened (including the retry count).

1. podium_health — confirm xcrun and maestro are available on the host.
2. device_list — pick 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, plus set_location and orientation_set.
5. Author end-to-end checks — inspect_screen to discover element text/ids, then run_flow (inline YAML or a .maestro file).
6. Capture & debug — screenshot or record_start → record_stop for video; metro_logs for live RN console output; crash_list / crash_get for diagnostics.

Contributions are welcome — see CONTRIBUTING.md and our Code of Conduct. Use the issue templates for bugs and feature requests.

Please report vulnerabilities privately per SECURITY.md — do not open a public issue.

MIT © 2026 hoainho