Chauffeur

What chauffeur does

The chauffeur MCP server lets a coding agent inspect and operate an iOS Simulator while receiving evidence about each action. It can expose the current accessibility hierarchy, locate elements by text or role, interact with controls, capture screenshots, and manage an app's lifecycle. It also follows logs for apps launched through it, allowing crash results to include the reported reason and recent log lines.

The tool is intended for simulator-based iOS development and testing. A successful action returns a screen diff. If a tap has no visible effect, the result identifies that condition instead of treating the command as completed. Other outcomes distinguish intercepted input, undelivered input, unverifiable changes, app crashes, and ordinary app exits.

How it works

The chauffeur MCP server keeps a daemon connection for each simulator so commands can reuse an existing connection. It reads the simulator's accessibility tree through Apple's private accessibility translator and presents the result as a compact outline with references for actionable elements. Agents can use those references instead of relying only on screen coordinates.

Touch commands are sent through the simulator's HID as finger events. After an action, chauffeur compares the accessibility tree before and after the command and checks the simulator's record of where the touch arrived. This produces statuses such as changed, NO EFFECT, INTERCEPTED, NOT DELIVERED, or UNVERIFIED. Logs and crash reports are tracked for applications launched by the tool.

Setup and configuration

The requirements are an Apple silicon Mac, Xcode 26 or 27, and a booted iOS Simulator. Homebrew installation is available with:

brew install yashnaj/chauffeur/chauffeur

Register the MCP process with Claude Code using claude mcp add chauffeur -- chauffeur mcp. The same executable can install agent guidance with chauffeur skill install; for Codex or Cursor, the project-level form is chauffeur skill install --agents codex,cursor, which writes the skill and an AGENTS.md section.

A simulator can be selected with --udid, the CHAUFFEUR_UDID environment variable, a directory-level .chauffeur.json file, or, when applicable, the only booted simulator. Run chauffeur doctor to perform environment and input checks. The MCP interface communicates over stdio and exposes the same command set as the CLI.

Tools and capabilities

The chauffeur MCP server provides capabilities for:

• Reading pruned accessibility snapshots, optionally with coordinates, and taking screenshots.
• Finding elements, waiting for elements to appear or disappear, tapping, typing, scrolling, and swiping.
• Pressing simulated Home, Lock, Siri, and volume buttons.
• Installing, launching, terminating, and deep-linking into apps.
• Reading launched-app logs and crash information.
• Granting, revoking, or resetting privacy permissions.
• Setting simulated location, sending push payloads, and changing light or dark appearance.
• Running multiple commands in sequence until the first failure.

The --json option returns structured data containing the command output, exit code, and text. Exit codes separately represent successful commands, errors, unverified effects, missing elements, crashes, and usage errors.

Limitations and notes

The chauffeur MCP server supports simulators only; physical iOS devices are not supported. It operates in portrait orientation and depends on Apple silicon and Xcode 26 or 27. Because it uses Apple's private simulator frameworks, an Xcode update may break compatibility and require diagnosis with chauffeur doctor.

Accessibility-driven inspection may not describe content rendered without an accessibility tree, such as some Metal or SpriteKit game interfaces. Screen text is returned as application data rather than agent instructions, so agents should treat it as untrusted input.