Headless Mode
Run Device MCP without its window, in a terminal, so your AI agent can use your devices on a Mac nobody watches.
Device MCP can run without its window: no window, no Dock icon, no menu bar item. It runs in a terminal, and your AI agent uses your iPhone, iPad, Apple Watch, Android devices, simulators and emulators through MCP, the same way it does with the window open. Your agent shows you what it sees with screenshots.
Use it on a Mac nobody looks at, such as a CI machine or a Mac mini you reach over SSH, or when you'd rather stay in the terminal.
1. Start Device MCP headless
Run this in a terminal (device-mcp-cli is Device MCP's command line):
device-mcp-cli headless
Device MCP starts right there and prints what happens: devices as they connect, each action your agent takes, and anything that needs you. Press Control-C to quit.
To keep it running in the background, or to open it without a terminal:
device-mcp-cli headless > device-mcp.log &
device-mcp-cli app open --headless
Stop it with device-mcp-cli app quit.
2. Connect your agent
Set up your agent as on the MCP page. While Device MCP runs headless, its MCP server is always on.
To let your agent start Device MCP headless by itself when it needs a device, add --headless at the end of the setup command:
claude mcp add --scope user device-mcp -- "/Applications/Device MCP.app/Contents/MacOS/device-mcp" --headless
codex mcp add device-mcp -- "/Applications/Device MCP.app/Contents/MacOS/device-mcp" --headless
3. See what your agent sees
There's no window to watch, so your agent is your eyes. It knows when Device MCP runs headless and shows you screenshots of the steps that matter. Ask for more any time: "show me the screen". It can also save screenshots and recordings to your Mac.
Your agent can do everything you'd do in the window: change Device MCP's settings, start and manage simulators and emulators, build your projects, manage the license and export diagnostics. Software updates and Factory Reset stay in the window.
4. Approvals and Human Handoff
Approvals and Human Handoff still ask you. They come as macOS notifications with their buttons, and in the terminal Device MCP runs in, where you can type:
| Type | What it does |
|---|---|
y | Allow Once |
a | Always Allow |
n | Deny |
done | You've finished on the device (Face ID, a passcode…). |
status | Device MCP's MCP server, license and devices. |
quit | Quits Device MCP. |
On a Mac nobody watches, allow the actions your agent needs for that run:
device-mcp-cli headless --allow all
5. Options
| Option | What it does |
|---|---|
--allow <actions> | Runs these actions without asking, for this run: all, or names separated by commas. |
--port <port> | The MCP server's port for this run. |
--json | Prints one JSON object per line, for scripts. |
--verbose | Also prints Device MCP's log. |