vphone-mcp

MCP server for programmatic control of vphone-cli iOS VMs. Enables AI-driven E2E testing by exposing the VM's display, touch input, and navigation as MCP tools.

How it works

Claude Code / Claude Desktop
    │ MCP (stdio)
    ▼
vphone-mcp (Python)
    │ Unix socket (JSON)
    ▼
vphone-cli (Swift, vm/vphone.sock)
    │ Virtualization.framework
    ▼
iOS 26 VM

Every action returns a compact grayscale screenshot (~20-30KB) inline in the response, so the LLM can see what happened without a separate call.

Setup

Requires uv and a running vphone-cli VM with the host control socket enabled (PR #261).

git clone https://github.com/pluginslab/vphone-mcp.git
cd vphone-mcp
uv sync

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "vphone": {
      "command": "uv",
      "args": ["--directory", "/path/to/vphone-mcp", "run", "vphone-mcp"],
      "env": {
        "VPHONE_SOCK": "/path/to/vphone-cli/vm/vphone.sock"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vphone": {
      "command": "uv",
      "args": ["--directory", "/path/to/vphone-mcp", "run", "vphone-mcp"],
      "env": {
        "VPHONE_SOCK": "/path/to/vphone-cli/vm/vphone.sock"
      }
    }
  }
}

Tools

Hardware Keys

Tool	Description
go_home	Press home button
press_power	Lock/wake the screen
volume_up	Volume up
volume_down	Volume down

Screenshots

Tool	Description
screenshot	Capture the VM display (returns embedded image)

Pre-mapped Navigation

Tool	Description
open_app(name)	Open an app by name from the home screen
tap_back	Tap the iOS back button (top-left)
scroll_down	Scroll down on current screen
scroll_up	Scroll up on current screen
open_notification_center	Swipe down from top-left
open_control_center	Swipe down from top-right
open_app_switcher	Slow swipe up from bottom
open_search	Tap the home screen Search bar
swipe_to_next_page	Swipe to next home screen page
swipe_to_previous_page	Swipe to previous home screen page

Supported app names for open_app: FaceTime, Calendar, Photos, Mail, Notes, Reminders, Clock, TV, Games, App Store, Maps, Health, Wallet, Settings, Phone, Safari, Messages, Music.

Raw Interaction

Tool	Description
tap(x, y)	Tap at pixel coordinates (1290x2796)
swipe(x1, y1, x2, y2, duration_ms)	Swipe between two points

Use screenshot() first to identify coordinates for app-specific UI elements.

Example session

User: Open Settings and navigate to General > About

Claude: [calls open_app("Settings")]
        → sees Settings list
        [calls tap(400, 1880)]
        → sees General page
        [calls tap(400, 1100)]
        → sees About page with iOS 26.1, Serial: vphone-1337

Configuration

Env var	Description
VPHONE_SOCK	Path to vphone.sock (auto-discovered if not set)

License

MIT