Skip to content
Back to search

vphone-mcp

MCP server for programmatic control of vphone-cli iOS VMs — AI-driven E2E testing

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pluginslab--vphone-mcp/badge.svg)](/listings/pluginslab--vphone-mcp)

HTML

<a href="/listings/pluginslab--vphone-mcp"><img src="/api/listings/pluginslab--vphone-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires [uv](https://github.com/astral-sh/uv) and a running vphone-cli VM with the host control socket enabled (PR [#261](https://github.com/Lakr233/vphone-cli/pull/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"
      }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 128 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # vphone-mcp
  2. MCP server for programmatic control of [vphone-cli](https://github.com/Lakr233/vphone-cli) iOS VMs. Enables AI-driven E2E testing by exposing the VM's display, touch input, and navigation as MCP tools.
  3. ## How it works
  4. ```
  5. Claude Code / Claude Desktop
  6. │ MCP (stdio)
  7. ▼
  8. vphone-mcp (Python)
  9. │ Unix socket (JSON)
  10. ▼
  11. vphone-cli (Swift, vm/vphone.sock)
  12. │ Virtualization.framework
  13. ▼
  14. iOS 26 VM
  15. ```
  16. Every action returns a compact grayscale screenshot (~20-30KB) inline in the response, so the LLM can see what happened without a separate call.
  17. ## Setup
  18. Requires [uv](https://github.com/astral-sh/uv) and a running vphone-cli VM with the host control socket enabled (PR [#261](https://github.com/Lakr233/vphone-cli/pull/261)).
  19. ```bash
  20. git clone https://github.com/pluginslab/vphone-mcp.git
  21. cd vphone-mcp
  22. uv sync
  23. ```
  24. ### Claude Code
  25. Add to `~/.claude/settings.json`:
  26. ```json
  27. {
  28. "mcpServers": {
  29. "vphone": {
  30. "command": "uv",
  31. "args": ["--directory", "/path/to/vphone-mcp", "run", "vphone-mcp"],
  32. "env": {
  33. "VPHONE_SOCK": "/path/to/vphone-cli/vm/vphone.sock"
  34. }
  35. }
  36. }
  37. }
  38. ```
  39. ### Claude Desktop
  40. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  41. ```json
  42. {
  43. "mcpServers": {
  44. "vphone": {
  45. "command": "uv",
  46. "args": ["--directory", "/path/to/vphone-mcp", "run", "vphone-mcp"],
  47. "env": {
  48. "VPHONE_SOCK": "/path/to/vphone-cli/vm/vphone.sock"
  49. }
  50. }
  51. }
  52. }
  53. ```
  54. ## Tools
  55. ### Hardware Keys
  56. | Tool | Description |
  57. |------|-------------|
  58. | `go_home` | Press home button |
  59. | `press_power` | Lock/wake the screen |
  60. | `volume_up` | Volume up |
  61. | `volume_down` | Volume down |
  62. ### Screenshots
  63. | Tool | Description |
  64. |------|-------------|
  65. | `screenshot` | Capture the VM display (returns embedded image) |
  66. ### Pre-mapped Navigation
  67. | Tool | Description |
  68. |------|-------------|
  69. | `open_app(name)` | Open an app by name from the home screen |
  70. | `tap_back` | Tap the iOS back button (top-left) |
  71. | `scroll_down` | Scroll down on current screen |
  72. | `scroll_up` | Scroll up on current screen |
  73. | `open_notification_center` | Swipe down from top-left |
  74. | `open_control_center` | Swipe down from top-right |
  75. | `open_app_switcher` | Slow swipe up from bottom |
  76. | `open_search` | Tap the home screen Search bar |
  77. | `swipe_to_next_page` | Swipe to next home screen page |
  78. | `swipe_to_previous_page` | Swipe to previous home screen page |
  79. 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.
  80. ### Raw Interaction
  81. | Tool | Description |
  82. |------|-------------|
  83. | `tap(x, y)` | Tap at pixel coordinates (1290x2796) |
  84. | `swipe(x1, y1, x2, y2, duration_ms)` | Swipe between two points |
  85. Use `screenshot()` first to identify coordinates for app-specific UI elements.
  86. ## Example session
  87. ```
  88. User: Open Settings and navigate to General > About
  89. Claude: [calls open_app("Settings")]
  90. → sees Settings list
  91. [calls tap(400, 1880)]
  92. → sees General page
  93. [calls tap(400, 1100)]
  94. → sees About page with iOS 26.1, Serial: vphone-1337
  95. ```
  96. ## Configuration
  97. | Env var | Description |
  98. |---------|-------------|
  99. | `VPHONE_SOCK` | Path to `vphone.sock` (auto-discovered if not set) |
  100. ## License
  101. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.