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