mcp

Project Url: phone-harness/mcp
Introduction: Connect AI agents to real iPhones and Androids
More: Author   ReportBugs   OfficialWebsite   
Tags:

Give any MCP agent a real iPhone or an Android emulator in the cloud.

Add Phone Harness as a custom connector in Claude, Cursor, ChatGPT, Codex, or any MCP client, and your agent can see the screen, tap, type, swipe, and open apps on a real iPhone or an Android emulator.

Setup

General

Streamable HTTP. Sign-in is OAuth and asks for the phone:drive scope. An API key can be sent as a bearer token instead; see the FAQ.

https://mcp.phone-harness.com/mcp

Add to Claude Add to Cursor Add to VS Code

  • Works in any MCP client. Claude, Cursor, ChatGPT, Codex, VS Code, and more.
  • Nothing to set up. No Mac, no adb, no pairing. Just a URL and a sign-in.
  • Real iPhones. Dedicated cloud iPhones, and Android emulators, driven the way a person uses them.

Claude

Use the Add to Claude button above, or open Customize → Connectors and add a custom connector (Add → Custom → Web, or Add custom connector). Name it Phone Harness, paste https://mcp.phone-harness.com/mcp, choose sign-in rather than No sign in, and add it. On Team and Enterprise, an Owner adds it under Organization settings → Connectors; members then connect.

Cursor

Use the Add to Cursor button above, or add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), then restart Cursor. Cursor signs in with OAuth when the server asks.

{
  "mcpServers": {
    "phone-harness": {
      "url": "https://mcp.phone-harness.com/mcp"
    }
  }
}

ChatGPT

On ChatGPT web, open Plugins → + → Add custom MCP server. Name it, paste https://mcp.phone-harness.com/mcp, choose sign-in, acknowledge the warning, and select Create as a plugin. Install the plugin, then @ mention it in a chat.

Custom MCP servers on ChatGPT web are for Business, Enterprise, and Edu workspaces. An admin creates the plugin. Pro accounts can connect a custom server for read and fetch tools only, so driving the phone needs Business, Enterprise, or Edu.

Grok

On grok.com/connectors, choose New Connector → Custom, paste https://mcp.phone-harness.com/mcp, and complete the sign-in. The server has to be reachable on the public internet.

In the Grok CLI, OAuth runs on first use:

grok mcp add --transport http phone-harness https://mcp.phone-harness.com/mcp

Claude Code

claude mcp add --transport http phone-harness https://mcp.phone-harness.com/mcp

Then run /mcp and sign in. That saves the server for the current project; add --scope user to keep it in every project.

Codex

codex mcp add phone-harness --url https://mcp.phone-harness.com/mcp
codex mcp login phone-harness

In the Codex IDE extension (gear menu → MCP servers) or the ChatGPT desktop app (Settings → MCP servers): Add server → Streamable HTTP, paste the URL, save, restart, and select Authenticate.

VS Code

Use the Add to VS Code button above. Or open the Command Palette, run MCP: Add Server, choose HTTP, and paste https://mcp.phone-harness.com/mcp. Sign in when asked.

The same server in the VS Code mcp.json format:

{
  "servers": {
    "phone-harness": {
      "type": "http",
      "url": "https://mcp.phone-harness.com/mcp"
    }
  }
}

Windsurf

Settings → Tools → Windsurf Settings → Add Server, or open the MCP config file from Cascade's MCP menu and add:

{
  "mcpServers": {
    "phone-harness": {
      "serverUrl": "https://mcp.phone-harness.com/mcp"
    }
  }
}

Cascade signs in with OAuth for a streamable HTTP server when no header is set. Press refresh after adding it.

Devin

In Devin, open Customize → MCPs → Add MCP → Add custom MCP. Set the transport to HTTP, the server URL to https://mcp.phone-harness.com/mcp, and authentication to OAuth. Save, then choose Connect. Adding a custom server needs the Manage MCP Servers permission.

In the Devin CLI:

devin mcp add phone-harness https://mcp.phone-harness.com/mcp
devin mcp login phone-harness

Gemini CLI

gemini mcp add --transport http phone-harness https://mcp.phone-harness.com/mcp

Gemini CLI discovers OAuth from the server. In a session, /mcp auth phone-harness starts the sign-in.

GitHub Copilot

copilot mcp add --transport http phone-harness https://mcp.phone-harness.com/mcp

That writes a streamable HTTP server to ~/.copilot/mcp-config.json. The default OAuth grant is the browser authorization-code flow.

Perplexity

Open Plugins → Add custom → Add MCP connector, and choose Remote. Name it, set the MCP server URL to https://mcp.phone-harness.com/mcp, and choose OAuth. For an organization, an admin adds it under Organization settings → Connectors.

Warp

Warp Drive → MCP Servers → + Add, choose Streamable HTTP, and set the URL to https://mcp.phone-harness.com/mcp with no headers. Warp’s docs show that a URL-only remote server opens a browser sign-in when it uses OAuth.

Raycast

Run Install MCP Server. Set the transport to HTTP, the URL to https://mcp.phone-harness.com/mcp, and OAuth to Dynamic. HTTP servers that use OAuth ask you to sign in before their tools are available.

Manus

Open Connectors → Create → Add MCP by URL. Enter a name and https://mcp.phone-harness.com/mcp.

OpenClaw

openclaw mcp add phone-harness --url https://mcp.phone-harness.com/mcp --transport streamable-http --auth oauth
openclaw mcp login phone-harness

Or in the Control UI: Settings → MCP → Add server, transport Streamable HTTP, then Sign in.

Muse Code

Add this to the mcp_servers block of the Muse Code settings file, then sign in:

{
  "mcp_servers": {
    "phone-harness": {
      "transport": "streamable_http",
      "url": "https://mcp.phone-harness.com/mcp"
    }
  }
}
muse mcp login phone-harness

Zed

Settings → AI → MCP Servers → Add Server → Add Remote Server, or add this to settings.json. With no Authorization header, Zed starts the MCP OAuth sign-in.

{
  "context_servers": {
    "phone-harness": {
      "url": "https://mcp.phone-harness.com/mcp"
    }
  }
}

Others

Any other client that can add a remote streamable HTTP server uses the URL above and the sign-in. Local stdio, Docker, and Vercel are in docs/self-hosting.md.

Tools

The hosted server registers these tools. Every tool in the first table except its first two takes device, an id from phone_list_available_devices.

Cloud Android emulators are free to start, then 5¢ per phone-minute, pay as you go. A Cloud iPhone is a flat monthly subscription, not billed by the minute: $80/mo, or $100/mo with an eSIM, with 20% off billed annually ($64/mo, or $80/mo with an eSIM). minutes on phone_start_device is how long the session runs (default 30), not a billing unit. See phone-harness.com/pricing for current rates.

Tool Does
phone_list_available_devices Running phones and their ids, the phones the account can start, and the account balance when the API reports one.
phone_start_device Start a phone and wait until it is ready. With nothing named, a temporary Android emulator starts. platform and kind go together (android/emulator, or ios/device for the account's iPhone). device_id picks a particular iPhone or a saved Android phone (apps and logins kept).
phone_stop_device End the session. Anything not saved on the phone is lost. Stopping cloud Android stops the per-minute charge.
phone_get_screen_size Screen size in the coordinate space taps and swipes use. It changes when the phone is turned.
phone_take_screenshot JPEG of the screen. Long side at most max_size (default 1024), or scale. The text before the image converts a point in the image to screen coordinates.
phone_list_elements_on_screen Visible text with tap-ready centers (text or json). Accessibility tree on Android; text recognition on iPhone.
phone_click_on_screen_at_coordinates Tap x, y.
phone_long_press_on_screen_at_coordinates Press and hold x, y for duration milliseconds (default 800, clamped to 100–10000).
phone_swipe_on_screen Swipe. direction is the way the finger moves (up reveals what is below). From x, y or the center, for distance pixels or 40% of the screen.
phone_type_keys Type text into the focused field. submit presses Enter.
phone_press_button HOME, BACK (Android only), APP_SWITCHER, or ENTER.
phone_wake Wake a cloud iPhone that is asleep, on its lock screen, or showing the StandBy clock, and get it past the lock screen. Cloud iPhones are set up with no passcode, so nothing is typed. iPhone only.
phone_open_url Open an https link in the iPhone's browser, whole, with no typing. url must start with https://, have no spaces, and be at most 4096 characters. iPhone only; the phone has to be awake.
phone_set_orientation Turn a cloud iPhone to portrait, landscape_left or landscape_right. The result gives the new screen size; coordinates read before the turn are stale. An app that supports only one way up stays that way. The phone has to be awake. If iOS's Portrait Orientation Lock is on, the turn switches it off first, which goes through Settings, takes about a minute and leaves the phone on its Home Screen; the lock then stays off until a turn back to portrait, which puts it on again. iPhone only.
phone_list_apps Installed apps: package ids on Android, bundle ids on an iPhone, when the phone can list them.
phone_launch_app Open an app by the name on its icon, or on Android by package id.
phone_get_foreground_app Which app is in front, when the phone reports it.

A cloud iPhone that has been left alone goes to sleep. Taps, typing and app launches are then refused until phone_wake is called, and the refusal says so. A local stdio server also registers phone_save_screenshot (write a PNG or JPEG on that machine). Tool names follow mobile-mcp.

Reserving a phone

An account with no cloud iPhone yet, or one that needs more of them, reserves them with a $20 per phone refundable deposit; the quote phone_reserve returns is authoritative. Reservations are for iPhones only (with or without eSIM). Cloud Android emulators are on the $20 plan and are not reserved. These tools take no device, and none of them pays: phone_reserve hands back a Stripe Checkout link, and a person opens it and pays the deposit. Nothing is reserved until they do.

Tool Does
phone_reserve Ask for iPhones: phone_type (iphone, or iphone_esim for one with an eSIM), plan (monthly or annual), use_case, what the phones are for, and quantity (1 to 50, default 1). Returns the quote (the deposit due now, and the plan's first billing period at the intro and standard prices) and the Checkout link for the deposit. first_name and last_name put a name on the reservation in place of the account's. idempotency_key repeats a call that failed part way without starting a second reservation.
phone_list_reservations The account's reservations, newest first: status, place in the queue, deposit, and when it was paid (text or json). With reservation_id, one in full, with its quote and, while it is unpaid, its Checkout link.
phone_cancel_reservation Give up a place in the queue. confirm must be true: without it nothing is cancelled, and the answer says what would be given up and refunded. The deposit still held is refunded to the card that paid. Refused once every phone has been handed over, because that deposit went onto the first bill.

A reservation is pending_payment until the deposit is paid, then queued with a position. Places go in the order deposits were paid; nothing moves one up. A customer's first phone is at the intro price, once, and every other phone at the standard price. Cancelling refunds the deposit still held automatically, to the card that paid. The plan starts when a phone is handed over; the deposit comes off its first bill and is then no longer refundable. An account can have five unpaid reservations an hour, and cancelling one does not free a place. Until the API has reservations, each of these tools says so and changes nothing.

FAQ

Can I use an API key instead of signing in?

Yes. Send Authorization: Bearer pck_… instead of going through OAuth. The buttons above do not include a key.

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

Codex reads the key from the environment:

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

Other API-key configs are in docs/self-hosting.md.

Development

uv sync
uv run pytest
uv run phone-harness-mcp --help

Report vulnerabilities per SECURITY.md.

License

MIT

Apps
About Me
GitHub: Trinea
Facebook: Dev Tools
AI Daily Digest