Swipium

Swipium

An MCP server that lets coding agents QA mobile apps on Android Emulators and iOS Simulators.

Swipium gives an AI coding agent (Claude Code, Codex, Gemini CLI, Cursor, VS Code, and other MCP clients) the tools a QA engineer uses: find or build the app, boot a simulator, install and launch it, read the screen, tap and type through real user flows, and write a report backed by screenshots, logs, and UI dumps. A run can be turned into a repeatable flow, a test suite, or Appium code.

It is for mobile developers who want their agent to catch the broken login screen before a TestFlight or Play Console build. It runs locally (stdio; the server opens no network port, and the WebDriverAgent it manages for iOS takes commands on 127.0.0.1 only, though its screen stream port is reachable from the network; see Security), drives devices through adb, simctl, and WebDriverAgent rather than Appium, and asks your consent before anything with side effects. swipium.com

A session, abbreviated

You:    Smoke test this app on Android with Swipium.

Agent > qa_test_this { goal: "smoke", waitForCompletion: true } (runs by default) 🔐 Consent required (low): • boot_emulator: emulator -avd Pixel_8_API_35 -no-audio -no-snapshot-save -no-boot-anim -gpu auto -no-window • install_apk: adb -s install -r -g android/app/.../app-release.apk You: Approve (one prompt covers boot + install) state: "running", sessionId: "3f9c2a1b", jobId: "a41c09e2" Agent > qa_job_status { sessionId: "3f9c2a1b", jobId: "a41c09e2", waitMs: 45000 } status: "done", result.state: "completed" reportHead: "RELEASE RISK: SHIP … Health: native OK, app OK … Open the report: …/report/report.html" nextRecommendedAction: qa_get_artifact { uri: "swipium://session/3f9c2a1b/report/…-summary.md" } Agent: The app launched and passed the smoke checks with no crashes or error screens.

Three calls: start the run, wait for it, and (only when the inlined head isn't enough) read report.md. The report behind that summary, rendered with npx swipium report --latest --format markdown, includes:

**Release risk: 🟢 SHIP**

App status: PASS - No high-severity app/native finding observed in this run. Coverage status: COVERED - Structured smoke/workflow evidence was collected. Tool status: PASS - No Swipium/MCP limitations or tool errors recorded in this run.

Contents

Requirements · Quickstart · Starter prompts · How it works · Tools · Where results go · Configuration · CLI · CI · Upgrading · Troubleshooting · Security

Requirements

Node.js 22.12 or newer. On an older Node.js the server prints a warning on stderr and swipium verify fails. Swipium works with emulators and simulators only; physical devices are refused with PHYSICAL_DEVICE_UNSUPPORTED (why). Structured iOS automation needs WebDriverAgent 6.0 or newer (qa_wda {action:"setup"} builds and starts one); without it an iOS Simulator is visual-only.

MCP: a stdio server that speaks protocol revisions 2025-06-18, 2025-11-25 and 2026-07-28; the client's first message picks one. Claude Code 2.1.285 and later connect on 2026-07-28, Codex 0.146 on 2025-06-18. Any stdio MCP client should work (protocol versions).

• Android: platform-tools, the Emulator, and at least one AVD (usually via Android Studio). adb on your PATH is used if present, else the SDK copy from $ANDROID_HOME, $ANDROID_SDK_ROOT, or the default SDK location (~/Library/Android/sdk, ~/Android/Sdk, %LOCALAPPDATA%\Android\Sdk). The emulator binary that boots AVDs and aapt2 come from the SDK first. .aab files need bundletool.
• iOS (macOS only): Xcode and a simulator. Taps, typing, and UI-tree snapshots need WebDriverAgent (WDA, the on-simulator automation server Appium uses); without it iOS is visual-only (iOS modes).

Quickstart

1. Register Swipium with your client. From your app repository, for Claude Code:

npx -y swipium init claude --scope project           # preview; changes nothing

npx -y swipium init claude --scope project --apply # writes .mcp.json and the skill, then runs swipium verify

For Claude Code, init also sets SWIPIUM_MAX_WAIT_MS=110000 (one call can wait up to 110 s, so most runs finish in one call) and installs the swipium-qa agent skill under .claude/skills/ (~/.claude/skills/ for --scope user; --no-skill skips it). --trust-local (local or user scope only) also pre-approves the consent actions that run no project code, so boots and installs stop prompting while builds, Metro and WebDriverAgent still ask. A Claude Code plugin with the same server and skill is in plugin/. Swipium is also listed in the MCP Registry as io.github.GeroPalombo/swipium, so registry-aware clients can find and install it.

The same command handles codex, gemini, cursor, and vscode (swipium init --apply). Claude Desktop, Windsurf, manual configs, and per-client details are in [docs/mcp-server.md](docs/mcp-server.md).

Codex: swipium init codex --apply appends a [mcp_servers.swipium] block to ~/.codex/config.toml (or $CODEX_HOME/config.toml) with longer timeouts and an env_vars line, and installs the skill under .agents/skills/. Codex doesn't pass your shell environment to MCP servers, so without that line SWIPIUM_TEST_*, ANDROID_HOME and JAVA_HOME never reach Swipium. If you already have a block, init prints the line to add. Keep tool_timeout_sec = 600 (Codex setup).

Headless runs (codex exec, claude -p, CI): these clients answer consent prompts automatically, so nothing gated (boot, install, build) runs unless you pre-approve exact actions with SWIPIUM_CONSENT_PREAPPROVE in the server env; approving in the chat doesn't help. Pre-approval isn't tied to a device, so on a machine with several emulators or simulators also pin one with SWIPIUM_DEVICE (Headless runs).

2. Restart the client and check that it lists qa_test_this, qa_doctor, and qa_report.

3. Ask the agent to test the app:

Use Swipium to smoke test this app: qa_test_this with goal "smoke" and

waitForCompletion true, poll qa_job_status while it is running, and summarize the report.

qa_test_this runs by default (mode:"execute", since 2.3.0); pass mode:"plan" for a side-effect-free preview. goal:"smoke" is the fastest path. With no goal, qa_test_this runs the smoke check and then tries to generate a test suite. With the skill installed, "test this app with Swipium" is enough.

If a tool returns PROJECT_ROOT_UNRESOLVED, name the absolute project path in your prompt or set SWIPIUM_PROJECT_ROOT in the server config (Project root).

What you'll see

• One approval prompt listing the exact build, boot, and install commands. Clients with MCP elicitation show a real prompt; others return requiresConsent, which the agent must relay to you.
• The first build can take minutes. The run is a background job. waitForCompletion waits up to about 45 s by default (about 105 s with the SWIPIUM_MAX_WAIT_MS=110000 that init claude sets). A qa_job_status poll returns at once unless the agent passes waitMs; Swipium tells it to pass 45000, and a poll is capped at 50 s (110 s with that setting).
• Two states. The job status is running, done, failed, or cancelled. The run's result.state is completed or needs_input (job done), or blocked or unsafe (job failed). needs_input means one question for you, such as login credentials.
• A report with separate verdicts for the app, coverage, and Swipium itself. A completed run inlines a short head (verdict, failures with their failing step and screenshot URI) and saves report.md for the agent; a blocked run names the fix. For you there is report.html: one self-contained page with the verdict, each failure with its screenshot and log, and the step timeline, which opens offline in any browser (the agent gives you its path, reportHtmlPath; what's in it).

Starter prompts

| Release gate | "Run Swipium with goal release_gate and tell me whether t