PreviewAPK MCP server

PreviewAPK — a phone for your AI agent

Your agent builds an Android app, and then… neither of you can see it run. No emulator on the machine, no device on the desk, and the Play Store is not a feedback loop.

PreviewAPK gives your agent a real cloud Android phone. Push an APK, it boots in the browser in seconds. The agent drives it — taps, types, screenshots, logs — and verifies its own work before you ever look. You watch the same phone through a link, take the wheel whenever you want, and every session gets a share link you can hand to a client or paste into a PR.

time; swap apps freely.

• $19/month per device, unlimited runs. One device runs one app at a

in the portal drives — one driver per session, switchable mid-session with an explicit handoff.

• Links are view-only, always. Only the owner's key (agent) or the owner

Maps, or FCM will hit that wall; everything else just runs.

• No Google Play services on the phones. Apps that need Google sign-in,

This repo is the open client: the CLI and the MCP server (both single-file, Python standard library only). The PreviewAPK service itself is hosted — you bring an API key from your account at previewapk.siteport.site. PreviewAPK is currently in waitlist beta; join there.

Quick start — CLI

curl -O https://previewapk.siteport.site/cli/previewapk.py
export PREVIEWAPK_API_KEY=pvk_…        # from your portal's Developers card

python3 previewapk.py devices          # see your devices
python3 previewapk.py use "Device 1"   # pick the working device (like cd)
python3 previewapk.py push app.apk --run
python3 previewapk.py tree             # the screen as an element tree
python3 previewapk.py tap --text "Log in"
python3 previewapk.py text "demo@example.com"
python3 previewapk.py shot             # a screenshot you can open
python3 previewapk.py logs --errors    # the app's logcat, noise filtered
python3 previewapk.py relaunch         # app back in front, ~2s, no reboot
python3 previewapk.py handoff user     # hand the human the wheel
python3 previewapk.py links            # the share link for the live session

Pushing to a running device hot-swaps the app in — installed and relaunched in the same session, no reboot.

Coordinates are fractions (0–1), never pixels; the CLI and API reject out-of-range values instead of silently tapping the wrong place, and text refuses when no field is focused instead of typing into the void. Signals an agent can trust: errors say what happened and what to do instead.

Quick start — MCP server

Hosted (zero install): point your MCP client at the remote server — same 27 tools, your API key as a Bearer token, nothing to download or keep current. Claude Code:

claude mcp add --transport http previewapk https://previewapk.siteport.site/mcp \
  --header "Authorization: Bearer pvk_…"

The server issues a session id at connect and your working-device selection rides on it, exactly like the local server. Hosted differences: previewapkpushapk takes apkb64 (base64) instead of a local path; file/record downloads return datab64.

Local (stdio): download previewapk_mcp.py from this repo, then register it with your MCP client. Claude Code:

claude mcp add previewapk \
  --env PREVIEWAPK_API_KEY=pvk_… \
  -- python3 /path/to/previewapk_mcp.py

Cursor / Claude Desktop / other MCP clients (JSON config):

{
  "mcpServers": {
    "previewapk": {
      "command": "python3",
      "args": ["/path/to/previewapk_mcp.py"],
      "env": { "PREVIEWAPK_API_KEY": "pvk_…" }
    }
  }
}

Shortened. The full README is on GitHub.