# poki [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/JosssphZhou/poki  
**GitHub Stars:** 1046  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/poki

## Description
Let AI agents operate a real iPhone. Local MCP server and agent, no jailbreak, no extra hardware.

## Claude Desktop Quick Installation
No generated config for this server: it installs through its own setup steps.

The project's own setup steps (from https://github.com/JosssphZhou/poki), copied verbatim. Run them in order; they are not an mcpServers config.

1. Install:

```sh
git clone https://github.com/JosssphZhou/poki.git
```

2. Install:

```sh
cd poki
```

3. Install:

```sh
./bin/setup
```

4. Start the server:

```sh
npm start
```

5. Install:

```sh
tar -xzf poki-v0.1.1-macos-arm64.tar.gz
```

6. Install:

```sh
cd poki-v0.1.1
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/poki/readme_