Phone Harness MCP

Connect AI agents to real iPhones and Androids.

The official Model Context Protocol server for Phone Harness. The agent sees the screen, taps, types, swipes, and opens apps on a real phone in Phone Harness Cloud, all over HTTPS. Nothing to pair, no adb, no Mac required, any OS.

Tool names follow mobile-mcp (phone_take_screenshot, phone_click_on_screen_at_coordinates, …), so an agent that has driven a phone before already knows how.

Use it two ways:

• Run it yourself with uvx phone-harness-mcp over stdio. It signs in as you: an API key, or the sign-in phone-harness cloud login left on the machine.
• Hosted at https://mcp.phone-harness.com/mcp. Nothing to install; your client sends your API key as a bearer token.

Requirements

• A Phone Harness Cloud account, and an API key from the dashboard (or the phone-harness CLI signed in with phone-harness cloud login).
• Python 3.10+ with uv for the local server. The hosted server needs nothing.

Getting started

Most clients take this standard config:

{
  "mcpServers": {
    "phone-harness": {
      "command": "uvx",
      "args": ["phone-harness-mcp"],
      "env": { "PHONE_HARNESS_API_KEY": "pck_…" }
    }
  }
}

Leave out env if the machine is already signed in with phone-harness cloud login.

claude mcp add phone-harness -e PHONE_HARNESS_API_KEY=pck_… -- uvx phone-harness-mcp

claude mcp add --transport http phone-harness https://mcp.phone-harness.com/mcp \
  --header "Authorization: Bearer pck_…"

codex mcp add phone-harness --env PHONE_HARNESS_API_KEY=pck_… -- uvx phone-harness-mcp

[mcp_servers.phone-harness]
url = "https://mcp.phone-harness.com/mcp"
bearer_token_env_var = "PHONE_HARNESS_API_KEY"

{
  "mcpServers": {
    "phone-harness": {
      "url": "https://mcp.phone-harness.com/mcp",
      "headers": { "Authorization": "Bearer pck_…" }
    }
  }
}

code --add-mcp '{"name":"phone-harness","command":"uvx","args":["phone-harness-mcp"],"env":{"PHONE_HARNESS_API_KEY":"pck_…"}}'

{
  "mcpServers": {
    "phone-harness": {
      "type": "local",
      "command": "uvx",
      "args": ["phone-harness-mcp"],
      "env": { "PHONE_HARNESS_API_KEY": "pck_…" },
      "tools": ["*"]
    }
  }
}

{
  "mcp": {
    "phone-harness": {
      "type": "local",
      "command": ["uvx", "phone-harness-mcp"],
      "environment": { "PHONE_HARNESS_API_KEY": "pck_…" },
      "enabled": true
    }
  }
}

What the agent does with it

● phone_list_available_devices        → no phone running; an iPhone and an Android are available
● phone_start_device                  → s_7f3a: Android emulator, 390x844, 30 min
● phone_launch_app name="Weather"
● phone_list_elements_on_screen       → "San Francisco" at (195, 212) …
● phone_take_screenshot               → forecast is up
● phone_stop_device

Tools

Every tool but the first two takes device, an id from phone_list_available_devices.

Not yet: opening a URL (url.open is not served by the session route today), installing apps, clipboard, screen recording.

Configuration

phone-harness-mcp [OPTIONS]

  --api-key KEY             API key. Default $PHONE_HARNESS_API_KEY, else the CLI's sign-in. stdio only.
  --api-url URL             Default $PHONE_HARNESS_CLOUD_API or https://api.phone-harness.com
  --port PORT               Serve streamable HTTP instead of stdio (see below)
  --host HOST               Interface for --port  [default: 127.0.0.1]
  --path PATH               MCP endpoint path  [default: /mcp]
  --allowed-hosts HOSTS     Host header values to accept; '*' disables the check
  --allowed-origins ORIGINS Origin header values to accept
  --public-url URL          The URL clients reach the server at (with --oauth-issuer)
  --oauth-issuer URL        Publish OAuth protected-resource metadata for this issuer
  --stateful                HTTP mode: one MCP session per client

Standalone and hosted server

--port serves streamable HTTP at /mcp:

uvx phone-harness-mcp --port 8931

In this mode the server holds no credential. Every request must carry Authorization: Bearer <API key>, which is forwarded unchanged to Phone Harness Cloud, so one process can serve many accounts and leaks none. A request without a bearer gets a 401 with a WWW-Authenticate challenge.

{
  "mcpServers": {
    "phone-harness": {
      "url": "http://localhost:8931/mcp",
      "headers": { "Authorization": "Bearer pck_…" }
    }
  }
}

Behind a reverse proxy pass the public hostname so the Host header is checked (DNS-rebinding protection): --host 0.0.0.0 --allowed-hosts mcp.example.com. mcp.phone-harness.com runs exactly this binary.

Vercel

The repo is also a Vercel project: app.py exposes the same server as one Python function, stateless, answering JSON. Import the repo in Vercel, add the domain, done. mcp.phone-harness.com runs this way.

vercel.json sets maxDuration to 300 s so phone_start_device can wait for a phone to boot.

Docker

docker build -t phone-harness-mcp .
docker run --rm -p 8000:8000 phone-harness-mcp --port 8000 --host 0.0.0.0 --allowed-hosts '*'

Security

• The server is a thin HTTPS client. It never holds a phone, and over HTTP it never holds a credential: each request's bearer is the only identity.
• Over stdio it uses this machine's sign-in, like any local MCP server; it is not a security boundary between you and your own account.
• Screenshots and text read from the phone pass through unlogged. API keys are never written to logs.
• Phones are rented by the minute. The phone_start_device description says so; turn on your client's tool-approval setting if you want to confirm it.

Report vulnerabilities per SECURITY.md.

Development

uv sync
uv run pytest            # a fake Phone Harness Cloud API; no account needed
uv run phone-harness-mcp --help

Layout: src/phone_harness_mcp/{cli,server,phone,cloud,screenshots,auth}.py. cloud.py is the HTTP client, phone.py turns API answers into sentences for the model, server.py is the tool set, auth.py is hosted-mode bearer handling.

License

MIT