IN PROGRESS

vphone-mcp

vphone-mcp is a professional Model Context Protocol (MCP) server designed for controlling vPhone virtual iOS devices. It provides a comprehensive set of tools for LLMs to interact with virtual iOS environments, including hardware control, location simulation, filesystem management, and application installation.

🏗️ Architecture

The project implements a robust Python-Swift bridge architecture:

• MCP Layer: Built with fastmcp in Python 3.13+, exposing high-level tools to MCP clients.
• Communication: Uses a high-performance Unix Domain Socket (UDS) bridge for low-latency communication.
• Bridge Client: A Python client (src/vphone_mcp/bridge/client.py) that communicates with the vphone-cli (Swift) daemon.
• Protocol: A custom binary-framed JSON protocol (src/vphone_mcp/bridge/protocol.py) ensures reliable message delivery and state management.

🛡️ Security Features

Security is a core pillar of vphone-mcp, implementing multiple layers of protection:

• API Token Authentication: All connections require a valid VPHONE_API_TOKEN. Tokens are used for HMAC-SHA256 signing of sensitive operations.
• Strict Path Validation: Filesystem operations are restricted to a whitelist of allowed directories (e.g., /var/mobile/Documents, /var/tmp) and protected against path traversal and symlink escape attacks.
• Two-Step Confirmations: Destructive or sensitive operations (deletion, renaming, IPA installation) follow a Preview-Confirm pattern. The preview step returns a short-lived (5-minute), single-use HMAC-signed token that must be provided to execute the final action.

🚀 Installation Guide

Prerequisites

• Python 3.13 or higher
• uv package manager
• vphone-cli (Swift) daemon running on the host

Setup

1. Clone the repository:

   git clone https://github.com/Lumysia/vphone-mcp.git
   cd vphone-mcp

2. Configure Environment Variables: Set the following environment variables in your shell or a .env file:

   export VPHONE_API_TOKEN="your-secure-api-token"
   export VPHONE_BRIDGE_SOCKET="/tmp/vphone_bridge.sock" # Default path
   export VPHONE_LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR

3. Run the Server:

   uv run vphone-mcp

🛠️ MCP Tool Reference

The server exposes 26 tools categorized for efficient device management:

Connection & Status

Tool	Description
vphone_connect	Connect to the vphone bridge and perform handshake.
vphone_disconnect	Disconnect from the bridge and clean up resources.
vphone_status	Get the current connection state (connected, disconnected, etc.).
vphone_ping	Measure round-trip latency to the bridge.
vphone_version	Retrieve protocol version and supported features.

Hardware & HID Control

Tool	Description
vphone_hid_press	Simulate a complete button press (down then up).
vphone_hid_down	Press and hold a HID button.
vphone_hid_up	Release a previously held HID button.
vphone_home	Simulate pressing the Home button.
vphone_power	Simulate pressing the Power button (sleep/wake/power dialog).
vphone_volume_up	Simulate pressing the Volume Up button.
vphone_volume_down	Simulate pressing the Volume Down button.

Location Simulation

Tool	Description
vphone_set_location	Set simulated GPS coordinates (lat, lon, alt, speed, course).
vphone_stop_location	Stop location simulation and revert to real GPS.

Filesystem Management

Tool	Description
vphone_file_list	List directory contents with metadata.
vphone_file_download	Download file content (base64/hex) or metadata.
vphone_file_upload	Upload file content to the device (no overwrite).
vphone_file_mkdir	Create a directory (optionally with parents).
vphone_file_delete_preview	(Secure) Preview deletion and get a confirmation token.
vphone_file_delete_confirm	(Secure) Execute deletion using a valid preview token.
vphone_file_rename_preview	(Secure) Preview rename/move and get a confirmation token.
vphone_file_rename_confirm	(Secure) Execute rename/move using a valid preview token.

Developer Mode & Apps

Tool	Description
vphone_devmode_status	Query the current developer mode status on the guest.
vphone_devmode_enable	Arm developer mode (requires a device reboot).
vphone_ipa_install_preview	(Secure) Validate an IPA and get an installation token.
vphone_ipa_install_confirm	(Secure) Execute IPA installation using a valid token.

🖥️ Client Configuration

To integrate vphone-mcp with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "vphone": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/vphone-mcp",
        "run",
        "vphone-mcp"
      ],
      "env": {
        "VPHONE_API_TOKEN": "your-secure-api-token",
        "VPHONE_BRIDGE_SOCKET": "/tmp/vphone_bridge.sock",
        "VPHONE_LOG_LEVEL": "INFO"
      }
    }
  }
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.