Podium MCP

podium-mcp

One baton. Every instrument.

A single MCP stdio endpoint with 51 tools for iOS (simulator + real) and Android device control, native UI automation, end-to-end flows, trustworthy assertions, React Native debugging, WebView DOM + network inspection, and a no-vision canvas/WebGL brain for Pixi/Konva/Fabric/Phaser/Three/Babylon (validated live in WebKit) — plus an experimental engine bridge for instrumented Unity/GL builds (AltTester) — one connection instead of half a dozen servers.

-2ea44f.svg)

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 eight capability sets behind a single stdio endpoint:

• Device & app management — iOS simulators (simctl), real iPhones (devicectl), and Android (adb) behind one platform-tagged device model.
• Native UI inspection & gestures — route through idb/mobilecli with a Maestro fallback (no per-gesture JVM spin-up).
• End-to-end flows & batch automation — declarative Maestro flows, ordered action batches, and an engineer→QA flow exporter.
• Trustworthy assertions — an *oracle ladder* (WebView-DOM › native a11y › Maestro) that returns falsifiable, evidenced verdicts and fails closed.
• WebView DOM + network — resolve WKWebView DOM to tap coordinates, evaluate JS, drive navigation, and capture in-page HTTP traffic as JSON/HAR.
• React Native debugging — Metro console logs, network requests, and in-app state over CDP, plus host/simulator crash reports.
• Real devices — Android emulator/device via adb (gestures + uiautomator hierarchy); real iOS via devicectl lifecycle + an opt-in WebDriverAgent backend.
• Canvas & game-engine automation, no vision — a *canvas/WebGL brain* drives Pixi/Konva/Fabric/Phaser/Three/Babylon UIs as addressable objects (validated live in WebKit). An experimental engine bridge drives Unity/GL via an AltTester-instrumented build (or a window.__podiumEngine WebGL bridge) — code-complete + mock-tested, not yet run against a live Unity build.

Rather than wiring several MCP servers into every client config, podium-mcp exposes everything behind one connection, with a shared execFile layer (no shell), consistent structured errors, automatic retry around Maestro's iOS-driver flakiness, and a single health-check tool to confirm what's available on the host.

Table of contents

• Why
• Benchmarks
• Requirements
• Install
• Usage
• Quick start
• The 51 tools
• The oracle ladder — trustworthy assertions
• Native-first gesture backend
• WebView & RN network introspection
• Documented limits
• Architecture
• Development & testing
• Roadmap & contributing
• Releasing
• Prompt playbook & references
• Design ideas
• Contributing · Security · License

Why

Driving a React Native app end-to-end usually means juggling several MCP servers — one for device/app control, one for UI flows, one for Metro/debugger logs, another for WebView inspection — each with its own config entry, quirks, and 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,
• evidenced verdicts so an agent knows when a flow *actually* worked.

Benchmarks

Podium is built on two choices that make it fast and cheap: it drives UIs as *structured data* — never screenshots — and routes gestures through a *native backend* with no per-action JVM spin-up.

Token economics — no-vision is ~5× cheaper

A screenshot-driven agent sends an image to a vision model on every step. Podium returns a compact structured element list instead. On an equivalent 8-step mobile flow (1179×2556 screenshots vs ~20-element lists):

vision loop  ████████████████████████████████  16,557 tokens

Podium ██████ 3,117 tokens (5.3× cheaper, −81%)

The gap compounds with every step — a 30-step session runs roughly 62k vs 12k input tokens. On top of per-step cost, the full 51-tool schema travels with every request (~3,612 tokens, ~71/tool); Podium keeps tool descriptions lean so the tool block never dominates the context window.

For canvas / WebGL UIs the advantage is structural, not just cheaper: the Canvas Brain addresses objects by name and text, where a screenshot-only agent must re-analyze pixels on every frame.

Speed — native-first gesture backend

Gestures route through idb / mobilecli instead of spinning up Maestro's JVM per action (measured on a live iPhone 16 Pro simulator):

One connection, not six

All 51 tools — device & app control, UI automation, declarative Maestro flows, evidenced assertions, WebView DOM + network capture, React Native / Metro debugging, and no-vision canvas/WebGL automation (plus an experimental engine bridge for instrumented Unity/GL) — sit behind a single stdio endpoint, replacing the usual stack of half a dozen separate MCP servers.

Token figures are heuristic estimates (~4 chars/token; Anthropic's ~750 px/token

image formula) — reproduce with npm run token-bench, or swap in the Anthropic

count_tokens API for exact counts. Speed figures were measured on a live

iPhone 16 Pro simulator (npm run benchmark).

Requirements

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

Platform scope (v0.3.0): podium automates iOS simulators, real iPhones (devicectl lifecycle + opt-in WebDriverAgent), and Android emulators/devices (adb gestures + uiautomator hierarchy). device_list tags each target with its platform and the backend is selected per target. When a toolchain (e.g. adb) is absent, those paths degrade to an informative result instead of failing.

Install

Claude Code plugin (recommended)

No manual config — one-time marketplace setup, then install:

/plugin marketplace add github:hoainho/podium-mcp

/plugin install podium-mcp@podium

The plugin auto-starts the MCP server (all 51 tools) and ships five skills:

npx (zero install)

{

"mcpServers": { "podium": { "command": "npx", "args": ["-y", "podium-mcp"] } } }

Manual (from source)

git clone git@github.com:hoainho/podium-mcp.git

cd podium-mcp npm install npm run build

Usage

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 51 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

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

Quick start (order of use)

1. `podium_health` — confirm xcrun / maestro / native backend availability.
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. Batch several with run_steps.
5. Author & verify — inspect_screen to discover elements, run_flow for declarative checks, then assert_visible / validate_flow for an evidenced verdict.
6. Inspect WebViews — webview_inspect → tap coordinates, webview_eval, webview_navigate, webview_network.
7. Capture & debug — screenshot / record_start→record_stop; `metro_lo