Skip to main content
Glama
pluginslab

vphone-mcp

by pluginslab
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pluginslab/vphone-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server