MCP Ios

mcp-ios

A Model Context Protocol server to drive an iPhone/iPad — the iOS counterpart to mcp-android. Read this first: iOS is fundamentally more locked down than Android or macOS, so this server takes the only legitimate route to real UI control.

The honest landscape

A stock iPhone does not allow a background app to see and control other apps the way Android's Accessibility service (or macOS) does. Apple's sandbox forbids it. So there is no on-device "iOS-use" agent like the Mac/Android ones. The viable routes, in order of capability:

This server implements the Appium/WDA route: it runs on a Mac, talks to a local Appium server driving WebDriverAgent on the tethered iPhone, and exposes the same safe-by-default MCP shape as the rest of the suite. A set_alarm-style action can also go through Shortcuts (run_shortcut) when the device isn't tethered.

If you want control *from the phone itself with nothing attached*, that isn't possible on iOS — use mcp-android on the Fold 7 for that experience, or the Shortcuts subset here.

Setup (Appium route)

brew install node

npm i -g appium appium driver install xcuitest

Xcode + command line tools installed; sign WebDriverAgent to your device once (Xcode)

Connect the iPhone by USB, Trust the Mac, enable Developer Mode on the device

appium # starts the Appium server (default http://127.0.0.1:4723)

The server creates the XCUITest session lazily on the first tool call, so it starts even before Appium or the device are up — the first call that needs the device returns a clear "start appium / sign WDA / connect the device" message if it can't connect.

Security model

Connection: IOS_APPIUM_URL (default http://127.0.0.1:4723), IOS_UDID (target device), IOS_BUNDLE_ID (optional default app). See .env.example for all variables and docs/CLIENTS.md for the full per-client install guide.

Tools

Read (read-only+): list_targets, device_info, screenshot, page_source (element tree), current_app, list_apps

Write (read-write+): tap, swipe, input_text, press_button (home/volume), launch_app, open_url, run_shortcut (via Shortcuts)

Admin (admin + IOS_ALLOW_MANAGE): install_app, terminate_app, reset_app (the last two confirm via elicitation; protected apps refused)

screenshot returns an MCP image content block so the agent can see the screen before acting.

Quickstart — add to your agent

Published on npm as @dockndevai/mcp-ios. No clone or build needed — your MCP client runs it on demand with npx. It must run on the Mac with a running Appium server. Start in `read-only` mode.

Claude Code (CLI)

claude mcp add ios -e IOS_APPIUM_URL="http://127.0.0.1:4723" -e IOS_MODE="read-only" -- npx -y @dockndevai/mcp-ios

Claude Desktop · Cursor · Windsurf — same block in claude_desktop_config.json, .cursor/mcp.json, or ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "ios": { "command": "npx", "args": [ "-y", "@dockndevai/mcp-ios" ], "env": { "IOS_APPIUM_URL": "http://127.0.0.1:4723", "IOS_MODE": "read-only" } } } }

VS Code (GitHub Copilot, Agent mode) — in .vscode/mcp.json:

{

"servers": { "ios": { "type": "stdio", "command": "npx", "args": [ "-y", "@dockndevai/mcp-ios" ], "env": { "IOS_APPIUM_URL": "http://127.0.0.1:4723", "IOS_MODE": "read-only" } } } }

Example prompts

• *"Take a screenshot of my phone and tell me what's on screen."*
• *"Open Safari and go to news.ycombinator.com."* (needs read-write)
• *"Run my 'Good morning' Shortcut."* (needs read-write)

Run from source (development)

npm install

npm run build node dist/index.js # with the environment variables set, and appium running

Develop

npm run dev

npm test # security policy + elicitation confirmation (pure; no device needed) npm run typecheck

The policy and elicitation tests are pure and run anywhere. The device-driving path can't be smoke-tested without a Mac + Xcode + signed WDA + a tethered iPhone, so it's built against your real device setup.

Publishing

This server ships a server.json for the official MCP registry and an mcpName for npm ownership validation. See [PUBLISHING.md](PUBLISHING.md) for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT