io.github.dockndevai/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 for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT