iOS Device Control

You can manage iOS simulators and real devices through a unified MCP server that exposes rich controls for automation, UI interactions, media handling, and AI-assisted workflows. This server pairs a versatile CLI and an MCP interface so you can automate testing, device sessions, and app lifecycles from scripts or AI assistants.

How to use

Start the MCP server in stdio mode to expose an API you can call from MCP clients or AI assistants. Use the basic command: chuk-mcp-ios mcp. You can customize the host, port, and log level as needed like chuk-mcp-ios mcp --host localhost --port 8080 or chuk-mcp-ios mcp --log-level DEBUG.

How to install

Prerequisites: you need Python and a compatible runtime. Ensure you have a working Python environment and, if you plan to use the CLI, the ability to install Python packages.

Option 1: Using uv (Recommended) Install and run the MCP server via uvx for a quick start.

Option 2: Using pip Install from source or from PyPI when published.

Configuration and usage notes

Start by running the MCP server in stdio mode so clients can connect. The preferred command is chuk-mcp-ios mcp. If you need a specific host/port, run chuk-mcp-ios mcp --host localhost --port 8080. For debugging, enable verbose logs with chuk-mcp-ios mcp --log-level DEBUG.

Environment variables you may configure include: IOS_CONTROL_LOG_LEVEL, IOS_CONTROL_LOG_DIR, IOS_CONTROL_DEFAULT_TIMEOUT, and IOS_CONTROL_BOOT_TIMEOUT. These control logging, directories for logs, and default timeouts to tune the automation experience.

CLI usage and automation with MCP

You can operate devices and sessions using the CLI or an MCP client. Common workflows involve listing devices, creating an automation session for a specific device or UDID, taking UI actions like screenshots or taps, and then terminating the session when you are done.

If you want to integrate with Claude or other assistants, connect to the MCP server you started and issue higher-level commands through natural language. The MCP endpoint accepts requests from your AI assistant and returns results like screenshots, app launches, or location changes.

Examples you can run now

# Start the MCP server in stdio mode
chuk-mcp-ios mcp

# Optional: start server on a specific host and port
chuk-mcp-ios mcp --host localhost --port 8080

# Enable verbose debug logging
chuk-mcp-ios mcp --log-level DEBUG

Security and access notes

Limit access to the MCP server to trusted clients. Use network controls to restrict who can connect to the MCP port, and consider enabling authentication or IP whitelisting if your environment requires it.

Troubleshooting and tips

If you encounter issues connecting from a client, verify the MCP server is running and listening on the expected port. Check the log directory for any error logs and ensure environment timeouts are adequate for your automation workloads.

Example quick-start flow: run the MCP server, connect with your MCP client, create a session for a target device, perform a UI action (like a screenshot or tap), then terminate the session when finished.

Notes on real devices and simulators

The server supports both iOS simulators and real devices. For simulators, ensure Xcode and the appropriate simulator runtimes are installed. For real devices, enable Developer Mode and connect the device to the host machine.

API and tool access

The MCP interface exposes tools to manage sessions, devices, apps, and UI actions. You can create sessions, list devices, launch apps, take screenshots, and control UI interactions through the MCP client or AI assistant.

Available tools

ios_create_session

Create a new automation session for an iOS device or simulator.

ios_list_devices

List available iOS devices and simulators.

ios_boot_device

Boot a specified simulator or bring a real device online for automation.

ios_screenshot

Capture a screenshot from the current session.

ios_launch_app

Launch an installed app by bundle ID within a session.

ios_tap

Simulate a tap gesture at given coordinates in a session.

ios_input_text

Type text into a focused UI element within a session.

ios_terminate_session

Terminate an automation session.

ios_list_apps

List installed apps within a session.