FAQ

Fix common problems

What you see	What to do
Missing prerequisite: <tool> from ./bin/setup	Install what the message names, then run ./bin/setup again. Setup keeps the existing .deps/idevice checkout, and Cargo continues its build.
Poki MCP needs the full Xcode from ./bin/setup	Only the Command Line Tools are active. Install Xcode and run the commands in the message.
Local Poki MCP is not running	Run npm start in the checkout. If you set POKI_MCP_STATE_DIR, set the same value for the daemon and the client.
Multiple devices match	Name the device: call select_device in an MCP client session, or pass device in each call.
The default port is in use	Run npm start -- --port <port>. Clients read the port from mcp.json.
A second daemon on one Mac	Give each daemon its own POKI_MCP_STATE_DIR. Both write mcp.json in that folder, and a normal shutdown removes it.
tap_text cannot find English text	A new simulator uses the language of the Mac. Target the text as it appears on screen.
This device is not recording from bin/call.mjs	A recording ends when its session closes. Record from one MCP client session.

Why is the command called poki-mcp?

The repository is poki. The command, the MCP server key, and the package name stay poki-mcp, because the npm name poki belongs to another project. package.json is marked "private": true; this repository is used from source and does not publish an npm package.

Known limits

• First release on physical iPhones: Portrait orientation only. Landscape control is unsupported. App container export (download_app_container) and direct Settings subpage links (open_settings with a page) are unavailable. Open Settings normally and navigate its visible controls instead. These limits do not change simulator support.

• Pasteboard (iOS 27 Simulator): On the tested iOS 27.0 runtime (24A5370g) and iOS 27.1 runtime (24A94425), simctl pbcopy leaves the simulator pasteboard empty. Because of this, set_clipboard fails its readback and non-ASCII text cannot reach a simulator field. fill reports this as a mismatch. Plain ASCII text does not use the pasteboard and is not affected.

• Emoji keyboard dismissal (iOS 27 Simulator): On the tested iOS 27 simulator, the emoji panel remains visible after toggling the keyboard. hide_keyboard truthfully reports failure while preserving field text; use the on-screen keyboard hide button or an app-supported outside tap instead.

• Settings & Accessibility services: Some Settings routes are unavailable. Simulator Reduce Motion and Reduce Transparency require direct Settings UI interaction, and a tested physical device returned not implemented for the larger-accessibility-sizes service.

• Signing & container permissions: Installing or building apps for physical devices requires valid Apple signing credentials (none are bundled), and container access is bound by platform permissions.

• Private Apple interfaces: CoreSimulator and physical-device bridges rely on Apple private interfaces whose behavior may change across OS releases. The size of the tool catalog does not imply complete tool/parameter validation across every iOS, macOS, or Xcode version.

• Crash symbolication: Only matches UUIDs and architectures from builds known to the current MCP session.

Disclaimers

• Speed scales with the model and service tier you choose. Actual time depends on the model service, your Mac, and the phone's state.
• Saved routes require the page to stay the same. When it changes, Poki falls back to the model.
• Screen contents are sent to your configured model service.
• Poki does not confirm actions on the device. It operates a real device as instructed, and you are responsible for any messages sent or payments made.
• Provided as is under the AGPL-3.0-only license, without warranty.
• Poki is not affiliated with Apple. iPhone and iMessage are trademarks of Apple.