Tapp MCP Server

Tapp — Playwright for iOS

Give your coding agent hands and eyes on the iOS simulator.

Coding agents can write Swift, but they can't see or touch the running app. Tapp fixes that: an MCP server that lets Claude Code, Cursor, Copilot — any MCP client — launch your iOS app on a simulator, tap, type, swipe, read the screen, take screenshots, and run autonomous QA that returns a deterministic ship/no-ship verdict. No test code required. No app changes required.

you:    "Add a logout button to the settings screen"
agent:  *writes the Swift*
agent:  *tapp: builds, opens the app, navigates to Settings, screenshots it*
agent:  "Done — and here it is working on the simulator: [screenshot]"

Quickstart

Requirements: macOS + Xcode (simulator runtimes installed), Node ≥ 18.

Claude Code:

claude mcp add tapp -- npx -y tapp-mcp mcp

Cursor / VS Code (Copilot) — add to ~/.cursor/mcp.json (Cursor) or .vscode/mcp.json (VS Code):

{
  "servers": {
    "tapp": { "type": "stdio", "command": "npx", "args": ["-y", "tapp-mcp", "mcp"] }
  }
}

Codex CLI — add to ~/.codex/config.toml:

[mcp_servers.tapp]
command = "npx"
args = ["-y", "tapp-mcp", "mcp"]

Any other MCP client: stdio command npx -y tapp-mcp mcp.

Optional but recommended (prebuilds the test harness so the first tool call is fast):

npx -y tapp-mcp install    # ~2 min, one time
npx -y tapp-mcp doctor     # verify Xcode / simulators / toolchain

Then ask your agent:

"Open com.mycompany.app on the simulator and screenshot the home screen." "Run autonomous QA on my app — is it ship-ready?" "Log in with test@example.com, drive to checkout, and record it as a replayable test."

What the agent gets (19 tools)

Full agent playbook: AGENTS.md — ships inside the package so agents can read it too.

The verdict you can trust

tapp_run_qa explores like a user — via the accessibility surface — and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces, navigation loops, and dead ends. The verdict is deterministic (no LLM in the run loop) and honest:

• blocked — a release-blocking issue was found.
• caution — issues to review, or the run couldn't see enough.
• ready — genuinely explored with no blockers. A shallow run is never ready — if the app crashed on launch or a login wall blocked exploration, you get inconclusive: true, not a false pass. Absence of findings is not a pass.

Apps behind a login? Pass testEmail/testPassword (typed into the login form automatically), appLaunchArgs (e.g. ["--uitesting"] if your app supports a bypass), or explicit loginSteps for custom login UIs.

CI gate

The same engine runs as a merge gate — explore on every PR, replay committed Flows, diff findings against a baseline, fail on regressions, post the report as a PR comment:

npx -y tapp-mcp ci --app path/to/MyApp.app --bundle-id com.mycompany.app

Or use the bundled GitHub Action (action.yml) on a macOS runner — see .github/workflows/autotap-gate-example.yml. Commit a .autotap/baseline.json from a main-branch run and PRs fail only on new high/critical findings, not pre-existing debt.

Make your repo agent-verified

Drop this into your iOS repo's AGENTS.md (read by Codex, Cursor, Copilot, Devin, Zed, …) so your agent proves its UI work instead of claiming it:

## Verifying UI changes
This repo uses Tapp (https://github.com/aarwitz/tapp) to verify work on the iOS simulator.
After any UI change: build + install the app, then use the tapp MCP tools (`npx -y tapp-mcp mcp`)
to open the changed screen and screenshot it as proof. Before declaring a feature done, run
`tapp_run_qa` and report the ship/no-ship verdict. A change is not "done" until it has been
seen working on the simulator.

How it works

A generic XCUITest harness attaches to any app by bundle id — no SDK, no code changes, no re-signing your app. It reads the accessibility tree, acts like a user, and streams structured OCQA_* markers (state, actions, issues, transitions) that the MCP server parses into trees, screenshots, findings, and the verdict. Everything runs locally on your Mac; nothing leaves it.

The first tool call builds the harness once (~2 min, cached in ~/.tapp; rebuilt automatically if you switch simulators). All captures land in ~/.tapp/captures/.

Coming soon

Tapp.app — a macOS cockpit around the same engine: import an iOS project, click Run, watch autonomous QA live, and get the ship/no-ship decision card. Free download, in packaging.

License

MIT