Skip to content
Black Friday: 30% offOnly this weekBF2026Get the deal →Explore the bundle
Device MCP

AI Agents

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:

TypeWhat it does
yAllow Once
aAlways Allow
nDeny
doneYou've finished on the device (Face ID, a passcode…).
statusDevice MCP's MCP server, license and devices.
quitQuits Device MCP.

On a Mac nobody watches, allow the actions your agent needs for that run:

device-mcp-cli headless --allow all

5. Options

OptionWhat 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.
--jsonPrints one JSON object per line, for scripts.
--verboseAlso prints Device MCP's log.