RELATED 01
Mobile MCP
Drives iOS and Android simulators, emulators and real devices from an assistant
10kGitHub stars
55k/wknpm downloads
96popularity score
tapflow
Drives iOS simulators and Android emulators on a self-hosted tapflow relay for agent-run mobile QA
By Duchan (individual) TypeScript Local · stdio TestingDeveloper tools
52 popularity score ★ 1.7k ↓ 405/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
It needs TAPFLOW_TOKEN. Replace each <NAME> with your value.
Claude CodeTerminal
claude mcp add tapflow -e TAPFLOW_TOKEN=<TAPFLOW_TOKEN> -- npx -y @tapflowio/mcp-serverClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"tapflow": {
"command": "npx",
"args": [
"-y",
"@tapflowio/mcp-server"
],
"env": {
"TAPFLOW_TOKEN": "<TAPFLOW_TOKEN>"
}
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"tapflow": {
"command": "npx",
"args": [
"-y",
"@tapflowio/mcp-server"
],
"env": {
"TAPFLOW_TOKEN": "<TAPFLOW_TOKEN>"
}
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"tapflow": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@tapflowio/mcp-server"
],
"env": {
"TAPFLOW_TOKEN": "<TAPFLOW_TOKEN>"
}
}
}
}Codex~/.codex/config.toml
[mcp_servers.tapflow]
command = "npx"
args = ["-y", "@tapflowio/mcp-server"]
[mcp_servers.tapflow.env]
TAPFLOW_TOKEN = "<TAPFLOW_TOKEN>"Gemini CLITerminal
gemini mcp add --scope user -e TAPFLOW_TOKEN=<TAPFLOW_TOKEN> tapflow npx -- -y @tapflowio/mcp-serverSettings 2
TAPFLOW_TOKEN |
Required: API-type personal access token (view, builds:write) from Settings → Tokens; 0.27.1 exits without it. |
|---|---|
TAPFLOW_RELAY_URL |
Optional: Relay WebSocket address; ws://localhost:4000 by default, wss://... for a remote relay. |
What it does
tapflow is a self-hosted system for streaming iOS simulators and Android emulators to a team's browsers: a relay server (Linux or Mac) plus a macOS agent that runs the devices. Its MCP server, the npm package @tapflowio/mcp-server with the program tapflow-mcp, is a small local process that talks to that relay over WebSocket and REST and hands a coding agent the devices as tools.
With it an agent can list and join device sessions, boot or shut down a simulator, install and launch builds already uploaded to the relay, take screenshots, read the screen as an accessibility tree, and tap, swipe, type or press keys and hardware buttons. It can also replay a tapflow flow file (YAML) on a device with no further model calls, which is how the makers suggest turning a scenario the agent worked out once into a repeatable check for CI.
The makers mark the whole automation side, the MCP server and the flow runner, as experimental; the manual QA dashboard is the mature part, and they expect rough edges in selector matching and timing just after an app starts.
The published version 0.27.1 registers 16 tools (packages/mcp-server/src/tools.ts at v0.27.1). The online guide is written for newer code: it lists list_runs and get_run, a token file and token-free use on the relay's own machine, none of which are in 0.27.1, whose index.ts exits at start without TAPFLOW_TOKEN.
What it needs
| Runtime | Node.js 22+ |
|---|
Node.js 22 or later for npx. A running tapflow relay (Node.js 22+, Linux or macOS) with at least one macOS agent: iOS needs macOS 26 or 27 with Xcode 26 or 27 and a simulator runtime, Android needs Java and the Android SDK with an AVD. A personal access token of the API type (view, builds:write) created in the dashboard under Settings → Tokens. Builds must already be uploaded to the relay.
Limits
Experimental by its makers' own label. Version 0.27.1 exits at start when TAPFLOW_TOKEN is unset or the relay cannot be reached, although the guide describes a token file (TAPFLOW_TOKEN_FILE) and token-free local use; those, and the list_runs and get_run tools, are not in the released package. On Android, screenshot always returns PNG; JPEG is honoured on iOS only. boot_device and shutdown_device wait up to 30 seconds. run_flow with a path only reads files inside the server's working directory; otherwise pass the YAML inline. It cannot upload builds, only install ones on the relay.
Who it suits
Suits teams that already run, or are willing to run, a tapflow relay and Mac agent and want a coding agent to drive their simulators for exploratory checks or to write flows that CI replays. It is a poor fit for anyone without a Mac to host the devices, for testing on real phones (tapflow is not a device farm), or for those who need a stable automation API, since the makers call this part experimental. Readers on 0.27.1 should follow the code, not the newer online guide, for token handling.
Tools 16
list_builds- Lists the apps and builds stored on the relay, with the ids other tools need
list_devices- Lists the simulators and emulators the relay knows about
connect_device- Joins a device session; needed before controlling the device
disconnect_device- Leaves a device session and releases it
boot_device- Starts a simulator or emulator and waits up to 30 seconds for it
shutdown_device- Powers a device off to free the Mac's resources
query_ui_tree- Returns the on-screen elements as an accessibility tree with roles, labels and frames
run_flow- Replays a tapflow YAML flow on a device, inline or from a file in the working directory
screenshot- Captures the device screen as PNG, or JPEG on iOS when asked
tap- Taps the screen at a coordinate
swipe- Swipes from one coordinate to another
type_text- Types text into the field that has focus
press_key- Presses a keyboard key by its key code name
press_button- Presses a hardware button such as home, lock or volume
install_app- Installs a build from the relay on the device
launch_app- Starts an installed app on the device