MCP server to control an iPhone from any agent

Every CLI command is an MCP tool with the same name and the same help text. Agents without a shell (Claude Code, Cursor, opencode, claude.ai) can lease an iPhone, read the screen and tap.

Remote MCP: the MCP client signs in once with OAuth and sends POST /mcp to the account hub on ghosthand.dev. The hub routes each call over the WebSocket tunnel to the Mac named by the lease prefix (studio:42), whose Controller and leases drive the iPhone over Bluetooth and USB. Each Mac also uses USB lockdown services and ImageCaptureCore.

Connect a client

Add the server URL to any client that supports streamable HTTP. The client signs in with the same Google account as your Macs.

1claude mcp add --transport http ghosthand https://ghosthand.dev/mcp

1234// opencode.json
{ "mcp": { "ghosthand": { "type": "remote", "url": "https://ghosthand.dev/mcp" } } }
// .cursor/mcp.json
{ "mcpServers": { "ghosthand": { "url": "https://ghosthand.dev/mcp" } } }

How tools map to the CLI

CLI	MCP
`ghosthand file push`	tool `file-push` (words joined by `-`)
`-l 42`	`lease: "studio:42"`
`--wait-text`, `--timeout-ms`	`waitText`, `timeoutMs`
`--screenshot`, `--screentext`	`screenshot: true`, `screentext: true` (images come back as image content)

File transfers use bytes, not Mac paths. Remote tools cannot read or write the Mac's filesystem. Send files as base64 data; downloads return to the MCP client. Use the local CLI when you need to select a source or destination on the Mac.

Several Macs

The tools reach every Mac signed in to your account. list shows each iPhone under its Mac. When more than one Mac is online, pass mac (the slug from list) to acquire, wait, setup and setup-status. Leases look like studio:42; pass them exactly as acquire printed them, because the prefix picks the Mac.

Tools

Each page below is generated from the daemon, so it is the exact text your agent sees. The CLI reference has the same commands with every flag.

Ask AI about this page