Poki

What poki does

poki connects an MCP client or the optional Poki Agent to a real iPhone. The project is designed for local operation on macOS and uses a native bridge to communicate with the device. It does not require a jailbreak or dedicated external hardware.

An agent can use the connected phone for tasks such as searching in Chrome and summarizing a result. Because the target is a real device, actions have real effects: sending a message or making a payment will be carried out if requested. Screen contents are sent to the model service configured for the agent.

The repository also includes Poki Agent, a separate terminal-oriented interface. It can retain past tasks and supports messaging channels after they are configured, including iMessage and Telegram.

How it works

The MCP server runs locally and remains active while an MCP client connects to it. The project includes a native bridge and device tooling for the macOS implementation. A connected iPhone is selected automatically when only one device is available; with multiple devices, a device UUID can be supplied.

Use node bin/call.mjs list_devices to find available device UUIDs. MCP clients can then invoke Poki's exposed tools through their normal MCP configuration. Claude Code, Codex, and other clients that accept mcpServers JSON are supported connection patterns.

For a physical iPhone, pair the device with the Mac over USB before using it. The project also documents Developer Mode, Wi-Fi, sessions, and remote connection behavior in its supporting guides.

Setup and configuration

The source installation targets macOS 15 or newer and requires full Xcode, Rust, Node.js 24 or newer, and ffmpeg. Clone the repository, run ./bin/setup to check and prepare dependencies, then start the server with npm start. The first build may take several minutes.

An Apple Silicon macOS package is also available. That package includes the native bridge and idevice tools, so Rust and the setup script are not needed. It still requires full Xcode, Node.js 24 or newer, Python 3, and ffmpeg. After starting the server, register the local src/stdio.mjs entry point with the MCP client.

The optional agent is installed separately with npm from the agent directory. Run poki login before using it, and use poki status to check its state. POKI_AGENT_MODEL changes the agent model, while POKI_NO_UPDATE_CHECK=1 disables the daily anonymous GitHub release check.

Tools and capabilities

• Discover connected devices with list_devices.
• Operate a real iPhone through MCP tools.
• Run tasks from the standalone Poki Agent.
• Start iMessage or Telegram control channels after authorization.
• Select a specific phone by device UUID when multiple devices are connected.

Limitations and notes

Physical-device support has been verified only with iPhones using the Chinese interface. Physical devices support portrait orientation only. App container export and direct links to Settings subpages are unavailable.

The main project targets macOS. Linux and Windows ports are maintained separately by community contributors. Keep the server running while using MCP or the standalone agent, and review requested actions carefully because the agent controls the actual phone.