Give Codex hands on your iPhone

ios-agent-bridge combines native iOS device services with UI automation and exposes them through one MCP interface.

It is an open-source control plane for devices you own or are authorized to administer. It lets Codex and other MCP agents select the best available iPhone provider instead of making the user learn AFC, DTX, WDA, Appium, RemoteXPC, or Web Inspector.

Status: v0.1.0 is an initial, installable integration release. Its physical-device support is always reported by live probes; it never claims that a capability works merely because a provider is installed.

What it can do

• Discover trusted iPhones and report a live capability matrix.
• Use pymobiledevice3 for deep, non-jailbreak device services such as device information, app/container work, diagnostics, and Web Inspector where upstream support and device setup allow it.
• Use Appium + WebDriverAgent for accessible UI automation: screenshots, UI trees, semantic element lookup, taps, gestures, text entry, app activation, URLs, and web contexts.
• Expose one tool surface over MCP and a matching ios-agent CLI.
• Execute a bounded server-side multi-step flow so an agent does not need an MCP round trip for every tap.
• Keep risky device actions locked behind an explicit safety policy.

What it deliberately cannot do

• It does not jailbreak devices, bypass pairing/trust, defeat a passcode, obtain root filesystem access, or circumvent Apple signing/security controls.
• It does not silently erase, restore, enter recovery/DFU, mutate security profiles, or delete an arbitrary tree of user files.
• A UI tree is accessibility data, not a guarantee that every pixel or private element is visible.
• Safari and embedded web inspection require the device/app settings Apple and Appium require; they are not fabricated when unavailable.

30-second quick start

git clone https://github.com/Joe15935/ios-agent-bridge.git
cd ios-agent-bridge
uv sync --all-groups
uv run ios-agent doctor
uv run ios-agent status
uv run ios-agent capabilities
uv run ios-agent setup-codex

doctor does not ask for, save, or print secrets. It tells you exactly which device-side action is needed when Apple requires one.

Requirements and setup

• macOS on Apple Silicon or Intel, Python 3.12+, and uv.
• A USB or paired Wi-Fi iPhone for real-device actions. The phone must be unlocked and trust this Mac.
• For rich UI automation, full Xcode (not Command Line Tools), an Apple development team for WDA signing, iOS Developer Mode, and Settings → Developer → Enable UI Automation. Run ios-agent doctor for the precise live status.
• For Safari/WebView DOM inspection, enable Web Inspector and Safari Remote Automation. Apps must expose inspectable WKWebViews.

Full Xcode, signing, trust, Developer Mode, and device unlocking are intentional user actions. The bridge never attempts to fake or bypass them.

Codex setup

ios-agent setup-codex uses the locally installed codex mcp add command rather than editing a guessed configuration format. It registers a local stdio MCP server named ios-agent and verifies it with codex mcp list. Start a new Codex task/session afterward so it loads the newly registered tools.

You can also run the server directly:

uv run ios-agent mcp

The project includes the ios-agent-operator skill, which teaches an agent to check status/capabilities first and use semantic UI operations before coordinate taps.

Provider routing

Provider	Role	Enabled by default
pymobiledevice3	Primary deep-device provider	Yes, when installed and paired
Appium XCUITest + WebDriverAgent	Primary UI provider	Yes, when Appium/WDA are healthy
go-ios	Fallback for a gap or a more reliable operation	No
libimobiledevice / ifuse	Compatibility layer for traditional iDevice utilities	No

The router records its preferred provider, fallbacks, and selection reason. It never starts competing RemoteXPC/tunnel owners for the same device.

Capability states

ios-agent capabilities returns the following real-time states rather than a generic error:

State	Meaning
READY	A live probe found a usable provider and required setup.
DEGRADED	A usable fallback exists with a stated limitation.
BLOCKED_SETUP	Install/configure a Mac-side dependency, such as full Xcode or Appium.
BLOCKED_USER_ACTION	The user must connect/unlock/trust the device, enable Developer Mode, or approve an Apple dialog.
UNSUPPORTED	iOS security or all upstream providers prevent the capability.
DANGEROUS_LOCKED	Intentionally unavailable in this release.

Safety and privacy

• READ actions are normal inspection actions.
• WRITE actions only run when a caller explicitly invokes the corresponding operation; file deletion also needs an explicit confirmation.
• DANGEROUS actions are locked. Version 0.1.0 intentionally exposes no erase/restore/DFU action.
• apps.uninstall and files.delete are destructive WRITE actions, require an exact target and confirm=true, and never recurse through a directory tree. File actions may target an app's vended Documents container only when that app explicitly permits it.
• Real artifacts are stored beneath ignored .local/, artifacts/, or private/ folders. The repository ignores pair records, certificates, keys, provisioning material, backups, logs, crash dumps, screenshots, media, cookies, and tokens.

Tests and verification

uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest
uv build
uv run python -c "from ios_agent_bridge.server import create_server; create_server()"
uv run ios-agent doctor --json
uv run ios-agent capabilities --json

pytest -m real_device is opt-in and never runs in public CI. A machine without a real iPhone reports LIVE_DEVICE_ACCEPTANCE_BLOCKED: NO_PHYSICAL_DEVICE rather than inventing evidence.

The release's conservative task-coverage evidence is recorded in the capability scorecard. It distinguishes implemented paths from simulator and physical-device verification.

Troubleshooting

Start with ios-agent doctor. The common remedies are:

1. Install and select full Xcode, then open it once to accept its license.

2. Connect, unlock, and trust the iPhone.

3. Enable Developer Mode and UI Automation on the iPhone for WDA.

4. Sign WDA with your own development team in Xcode.

5. Install the narrow Appium XCUITest driver only after Xcode is ready:

   npm install -g appium@3.6.0
   appium driver install xcuitest@12.3.2
   appium driver doctor xcuitest
   

The bridge binds an auto-started Appium server to 127.0.0.1, uses Appium 3's root base path, and never enables --relaxed-security.

Credits and license

ios-agent-bridge is GPL-3.0-or-later. It integrates upstream projects rather than vendoring or forking their protocol implementations. See THIRD_PARTY_NOTICES.md for licenses and attribution.

Key upstream projects: pymobiledevice3, Ghost in the Droid, Appium, Appium XCUITest Driver, WebDriverAgent, go-ios, libimobiledevice, ifuse, and the official Model Context Protocol Python SDK.