Enables programmatic opening and navigation of the App Store within an iOS virtual machine environment.
Provides programmatic control over iOS virtual machines, enabling touch input, hardware button simulation, screen capture, and navigation for automated E2E testing.
Enables programmatic opening and interaction with the Safari web browser within an iOS virtual machine.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vphone-mcp open the Settings app and navigate to General"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Claude Code / Claude Desktop
│ MCP (stdio)
▼
vphone-mcp (Python)
│ Unix socket (JSON)
▼
vphone-cli (Swift, vm/vphone.sock)
│ Virtualization.framework
▼
iOS 26 VMEvery action returns a compact grayscale screenshot (~20-30KB) inline in the response, so the LLM can see what happened without a separate call.
Related MCP server: iOS Device Control MCP Server
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 syncAdd 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"
}
}
}
}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"
}
}
}
}Tool | Description |
| Press home button |
| Lock/wake the screen |
| Volume up |
| Volume down |
Tool | Description |
| Capture the VM display (returns embedded image) |
Tool | Description |
| Open an app by name from the home screen |
| Tap the iOS back button (top-left) |
| Scroll down on current screen |
| Scroll up on current screen |
| Swipe down from top-left |
| Swipe down from top-right |
| Slow swipe up from bottom |
| Tap the home screen Search bar |
| Swipe to next home screen 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.
Tool | Description |
| Tap at pixel coordinates (1290x2796) |
| Swipe between two points |
Use screenshot() first to identify coordinates for app-specific UI elements.
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-1337Env var | Description |
| Path to |
MIT
Press the home button to return to the home screen.
Inputs: no named parameters. Returns: result
Open an app from the home screen by name.
First presses home to ensure we're on the home screen, then taps the app.
Supported apps: FaceTime, Calendar, Photos, Mail, Notes, Reminders, Clock, TV, Games, App Store, Maps, Health, Wallet, Settings, Phone, Safari, Messages, Music.
Inputs: name (required). Returns: result
Slow swipe up from bottom to open the App Switcher.
Inputs: no named parameters. Returns: result
Swipe down from the top-right to open Control Center.
Inputs: no named parameters. Returns: result
Swipe down from the top-left to open Notification Center.
Inputs: no named parameters. Returns: result
Tap the Search bar on the home screen.
Inputs: no named parameters. Returns: result
Press the power button (lock/wake).
Inputs: no named parameters. Returns: result
Take a screenshot of the VM display and return it as an image.
Returns the screenshot as an embedded image that can be analyzed visually.
Inputs: no named parameters.
Scroll down on the current screen.
Inputs: no named parameters. Returns: result
Scroll up on the current screen.
Inputs: no named parameters. Returns: result
Swipe from one point to another.
Coordinates are in pixels matching the screenshot dimensions (1290x2796).
Args: x1: Start X coordinate y1: Start Y coordinate x2: End X coordinate y2: End Y coordinate duration_ms: Swipe duration in milliseconds (default 300)
Inputs: x1 (required), y1 (required), x2 (required), y2 (required), +1 more. Returns: result
Swipe left to go to the next home screen page.
Inputs: no named parameters. Returns: result
Swipe right to go to the previous home screen page.
Inputs: no named parameters. Returns: result
Tap at specific pixel coordinates on the screen.
Coordinates are in pixels matching the screenshot dimensions (1290x2796). Use screenshot() first to identify the target position.
Args: x: Horizontal pixel coordinate (0=left, 1290=right) y: Vertical pixel coordinate (0=top, 2796=bottom)
Inputs: x (required), y (required). Returns: result
Tap the iOS navigation back button (top-left corner).
Inputs: no named parameters. Returns: result
Press volume down.
Inputs: no named parameters. Returns: result
Press volume up.
Inputs: no named parameters. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 17 tools
Each tool has a clearly distinct purpose with no overlap; for example, go_home, open_app, and open_app_switcher perform different navigation actions, while tap, swipe, and screenshot handle distinct interactions. The descriptions specify unique functions, making it easy for an agent to select the correct tool without confusion.
All tool names follow a consistent verb_noun pattern (e.g., go_home, open_app, scroll_down, tap_back), with no deviations in style or casing. This predictability enhances readability and usability for agents, ensuring a coherent naming convention throughout the set.
With 17 tools, the server is well-scoped for simulating iOS device interactions, covering navigation, input, and system controls. Each tool serves a specific function (e.g., scrolling, tapping, opening apps), and the count aligns with the domain's complexity without being excessive or insufficient.
The tool set provides comprehensive coverage for basic iOS simulation, including navigation, app launching, gestures, and system actions. Minor gaps exist, such as lack of tools for typing text or adjusting settings beyond volume, but agents can work around these using existing tools like tap for input fields.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Cloud iPhones and Macs with Xcode for AI agents: build, run and test iOS apps, use the screen.
Cloud iPhone Simulators for AI agents: build the Xcode project, read the screen, tap by label, test.
Build, run, and inspect iOS apps in disposable hosted Simulators from cloud coding agents.
