How to use phonedriver with Codex

Add phonedriver to OpenAI Codex as an MCP server with one command, a config.toml entry or a plugin, pick a device, and ask Codex to operate a phone.

Codex can operate an Android phone or an iPhone through phonedriver. Run codex mcp add phonedriver -- npx -y phonedriver mcp, connect a device, and ask in plain language.

phonedriver is tested with Claude Code. In Codex 0.167.0 I installed the plugin and saw its MCP server and its skill load. The benchmarks on this site were not run in Codex.

Add the server

With Node 18 or later and nothing installed first:

codex mcp add phonedriver -- npx -y phonedriver mcp
codex mcp list

Inside a Codex session, /mcp shows the active servers. The first start downloads the binary once (see Install). If you installed phonedriver, use codex mcp add phonedriver -- phonedriver mcp.

With more than one device connected, name the one to use. phonedriver devices lists the ids.

codex mcp add phonedriver --env PHONEDRIVER_DEVICE=android:emulator-5554 -- npx -y phonedriver mcp

Or edit config.toml

Codex keeps its MCP servers in ~/.codex/config.toml, or in .codex/config.toml inside a trusted project. The same server as a table:

[mcp_servers.phonedriver]
command = "npx"
args = ["-y", "phonedriver", "mcp"]

[mcp_servers.phonedriver.env]
PHONEDRIVER_DEVICE = "android:emulator-5554"

Leave the env table out when one device is connected. The command and the file format are from Codex's MCP documentation, read on 14 November 2026.

Or install the plugin

The plugin adds the same server and the phonedriver skill, so Codex has the instructions without you pasting them. Use the plugin or mcp add, not both, or the tools are listed twice.

codex plugin marketplace add hridaya423/phonedriver
codex plugin add phonedriver@phonedriver

Ask it

Start an Android emulator, plug in an Android phone with USB debugging on, or boot the iOS Simulator. Then ask:

Open Settings and turn on dark mode.

Codex gets the screen as a short numbered list and taps by number. Each action waits for the screen to settle and returns only the lines that changed:

ok tapped @e10 "Dark theme"
~ @e10 switch "Dark theme" off → on

Approval prompts in Codex

The approval guard holds a tap on Pay, Place order or Delete account and asks you through MCP elicitation. Codex's MCP documentation does not say whether Codex supports elicitation, and I have not tried the prompt there. In a client that cannot show the question, the tool replies Needs the human's approval; nothing was tapped, and the agent has to ask you in chat. Read what the guard does not catch before you give an agent a phone with a payment app on it.

Without MCP

An agent with a shell can run the same commands as a CLI, and the text is the same as the MCP tools return:

npx -y phonedriver snapshot
npx -y phonedriver tap @e4

npx -y phonedriver skill prints the instructions an agent should read first.

Questions

Can Codex control a real iPhone?

Yes, from a Mac with Xcode. Plug the iPhone in, run phonedriver ios setup once, and Codex uses it through the same MCP server. phonedriver ios wifi on lets you unplug the cable afterwards. See the iPhone guide.

Does Codex need the phonedriver skill?

It helps. The MCP server carries a short version of the instructions, and the skill holds the full strategy, such as sending a path of taps in one call. The plugin installs the skill. With codex mcp add, npx -y phonedriver skill prints it.

How many tokens do the tools cost?

In Claude Code, the first turn of a one-word claude -p costs 5,606 tokens with phonedriver's 14 tools attached. I have not measured the same turn in Codex. See the token benchmark.