JosssphZhou/poki

What it does

Poki is an MCP server and optional terminal agent that let an AI agent operate a physical iPhone through a Mac. You connect your existing MCP client (Claude Code, Codex, or any client that supports mcpServers JSON) or use the bundled poki agent, and the agent can inspect the screen and perform actions on the phone. The project states that no jailbreak or extra hardware is required, and that it works with simulator and physical-device adapters through a native bridge.

It is aimed at developers who already use an LLM agent and want it to drive iOS UI tasks, for example searching in an app and summarizing results. The agent keeps task history so repeat tasks run faster, and can be reached from iMessage or Telegram after a channel is configured.

Quick start

Requirements on the Mac: Apple Silicon, macOS 15 or later, full Xcode, Rust, Node.js 24+, and ffmpeg. Clone the repository and run the setup script:

 git clone https://github.com/JosssphZhou/poki.git
 cd poki
 ./bin/setup
 npm start

Keep the server running, then register the MCP server from the same directory in another terminal:

claude mcp add --scope user poki-mcp -- node "$PWD/src/stdio.mjs"   # Claude Code
codex mcp add poki-mcp -- node "$PWD/src/stdio.mjs"                 # Codex

To use the standalone agent instead, install it in the same directory, put bin on PATH, and sign in:

npm ci --prefix agent
export PATH="$PWD/bin:$PATH"
poki login
poki status

A prebuilt poki-v0.1.0-macos-arm64.tar.gz package is also available from releases; it includes the native bridge and idevice tools, so Rust and ./bin/setup are not needed, but Xcode, Node.js 24+, Python 3, and ffmpeg are still required. For a physical iPhone, pair it over USB first and follow the physical iPhone setup. Then check the device and run a task:

node bin/call.mjs list_devices
poki "Search esp32 in Chrome and summarize the top result"

With multiple devices, pass --device '<device UUID>'. The install guide, tool reference, and configuration document the remaining options.

Constraints

• Platform: macOS on Apple Silicon only; the project badges list macOS and iOS, with the Mac as the host.
• Physical-device verification is limited to iPhones using the Chinese interface; portrait orientation only. App container export and direct links to Settings subpages are unavailable on physical devices.
• The agent controls the real phone. If asked to send messages or make payments, it will, and screen contents are sent to the configured model service.
• Automating third-party apps may violate their terms of service, and account restrictions are the user's responsibility. The software is provided as-is under AGPL-3.0-only.

HotRepo's take

The project appeared on HotRepo's new-project list on 2026-11-05, recording 108 stars and 29 forks in a window of roughly 2 hours 41 minutes from UTC 15:04 to 17:45. That single snapshot shows fast early attention, but it is too short a series to judge a trend, and there is no GitHub daily-rank record for the repository yet. The useful signal is the scope: an MCP interface to a real phone fills a gap that most coding-oriented MCP tools do not cover, while the macOS/Xcode dependency and the narrow physical-device verification keep it a developer tool rather than a general consumer app.