Connect AI tools

Keep npm start running. Your MCP client connects to the running server and does not launch it.

Connect an MCP client

Replace /absolute/path/to/poki with the absolute path to your checkout, and ensure node (24+) is on the MCP client's PATH.

From the checkout, "$PWD/src/stdio.mjs" gives the same absolute path in a shell command.

Claude Code:

claude mcp add --scope user poki-mcp -- node /absolute/path/to/poki/src/stdio.mjs

Codex:

codex mcp add poki-mcp -- node /absolute/path/to/poki/src/stdio.mjs

Codex (config.toml):

[mcp_servers.poki-mcp]
command = "node"
args = ["/absolute/path/to/poki/src/stdio.mjs"]
startup_timeout_sec = 30
tool_timeout_sec = 900

Clients using mcpServers JSON:

{
  "mcpServers": {
    "poki-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/poki/src/stdio.mjs"]
    }
  }
}

Let your agent install it

Paste this prompt into your agent to let it set everything up:

Please install Poki MCP and connect it to yourself:
1. Run git clone https://github.com/JosssphZhou/poki.git, then ./bin/setup in that folder.
   If setup names a missing tool, stop and tell me which one.
2. Run npm start in that folder as a background process that keeps running.
   It is ready when it prints a line containing "event":"ready".
3. Add the MCP server to your own client only, and keep the existing configuration:
   Claude Code: claude mcp add --scope user poki-mcp -- node <absolute path>/src/stdio.mjs
   Codex: codex mcp add poki-mcp -- node <absolute path>/src/stdio.mjs
4. Call poki_mcp_status and tell me total_tools.
   If the new server only loads in a new session, tell me so.

Verify from the terminal

Each stdio MCP client gets its own session, keeping its select_device choice until the client exits. bin/call.mjs works differently: each run opens a session named terminal, makes a single call, and closes the session on exit. Even though runs use the same session name, they do not share state, so device selections and recordings do not carry over to the next run. Pass device in each call, or use an MCP client session to persist your selection:

node bin/call.mjs poki_mcp_status
node bin/call.mjs list_devices
node bin/call.mjs start_simulator '{"model":"iPhone 18 Pro"}'
node bin/call.mjs take_screenshot '{"device":"YOUR_DEVICE_NAME_OR_ID"}'
node bin/call.mjs list_elements '{"device":"YOUR_DEVICE_NAME_OR_ID","source":"accessibility"}'

list_devices with {"include_all_simulators":true} lists the models that start_simulator can create. start_simulator names a new simulator Poki MCP <model>.

To use a physical iPhone, first pair it with your Mac over USB. After that, keep both devices on the same local network with the phone unlocked. See Physical iPhone setup.

Use it

Ask your agent for the task you want done:

Start an iPhone simulator, open Settings, and tell me the iOS version.

Three tools handle most interactions:

• batch_commands runs a known multi-step task in a single call and returns the visible on-screen text at the end, saving a screenshot round trip.
• fill focuses an input field, replaces its text, and verifies the new value.
• tap_text waits up to five seconds for its target to appear. If the target is not found, it aborts without tapping and returns what is currently on screen.

Installing apps, opening URLs, and reading the clipboard trigger a macOS approval dialog on your Mac. See Approval & Clipboard Behavior.

Configuration and sessions

All device operations are serialized inside the daemon. Every setting below is optional:

Setting	Purpose
POKI_MCP_STATE_DIR	Override the state and endpoint directory. Must be set to the same value for both daemon and client.
POKI_MCP_SESSION	Session identifier (1–80 characters: letters, digits, _, or -). Simultaneously connected clients with the same identifier share a session and its device selection, while distinct identifiers isolate them. The session closes as soon as any sharing client exits. Because of this, a shared value will not preserve a selection across separate bin/call.mjs runs, and reusing a running client's identifier in bin/call.mjs will clear that client's selection when the command exits.
POKI_MCP_APPROVAL_MODE=allow	Preapprove sensitive operations (listed under Approval & Clipboard Behavior) for this daemon instance. Omit for interactive local approval prompts.
POKI_MCP_NATIVE_TRACE	Enable native diagnostic timing output on stderr.
IDEVICE_TOOLS	Optional path override for the pinned upstream CLI.

The authenticated local HTTP bridge passes the session via the x-poki-mcp-session header. Standard MCP clients should always connect through src/stdio.mjs; the local token file is not a remote access mechanism.

poki_mcp_status reports the version from the root package.json, the current short Git commit (unknown outside Git), and native_build, the bridge file’s UTC modification time (unknown when absent). A daemon startup warning reports Rust source or Cargo metadata newer than the bridge. It does not block startup or rebuild anything.