ios_mcp

<p align="center"> <img src="assets/banner.svg" alt="ios-mcp — headless iOS dev, straight from the CLI" width="700"> </p> <p align="center"> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square" alt="MCP Compatible"></a> <a href="https://github.com/apple/swift"><img src="https://img.shields.io/badge/Swift-6.1+-F05138?style=flat-square&logo=swift&logoColor=white" alt="Swift 6.1+"></a> <a href="https://developer.apple.com/xcode/"><img src="https://img.shields.io/badge/Xcode-16+-147EFB?style=flat-square&logo=xcode&logoColor=white" alt="Xcode 16+"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License"></a> </p> <p align="center"> An <a href="https://modelcontextprotocol.io/">MCP</a> server for the iOS development lifecycle — <b>71 tools</b> for project discovery, simulator &amp; device management, building, testing, UI automation, debugging, navigation, package management, and quality checks. Works with any MCP-compatible client. </p>

---

💡 Why ios-mcp

• Single native binary — one make install and you're running. No runtimes, no interpreters, no background daemons. Optional tools (axe, SwiftLint) enhance specific features but aren't required.
• Interactive debugging — attach to processes, set breakpoints, inspect stacks and variables, execute LLDB commands — all through MCP. Go beyond build-and-test into real debugging workflows.
• Deep UI automation — tap, swipe, type, long press, screenshot, record video, read the full accessibility tree. Drive the simulator the way a user would.
• Security by default — secrets are automatically redacted from all output (tokens, keys, signing identities). Dangerous debugger commands are blocked. All subprocesses use argument arrays — never shell execution. No telemetry. No network access.
• Post-mortem analysis — parse crash logs with symbolicated backtraces, inspect xcresult bundles for diagnostics, test failures, code coverage, and build timelines. Understand what went wrong without leaving the terminal.
• Session intelligence — tools auto-discover context (workspace, scheme, simulator, device) and validate it before use. Stale defaults are caught, not silently reused. Every response includes suggested next steps for natural workflow progression.
• Graph-based navigation — load a navigation graph describing your app's screens and transitions, then navigate deterministically via BFS pathfinding. Supports deeplinks, taps, swipes, text input, and key presses. Works without a graph too — tools gracefully fall back to direct UI automation.
• Full lifecycle coverage — 71 tools spanning project discovery, simulator and device management, building, testing, UI automation, debugging, navigation, logging, Swift packages, crash analysis, and quality checks.

---

⚡ Quick Start

# Install
git clone https://github.com/JAManfredi/ios_mcp.git && cd ios_mcp
make install

# Verify
ios-mcp doctor

---

🛠 What's Included

71 tools across 13 categories:

| Category | Count | Tools | |----------|:-----:|-------| | 🔍 Project Discovery | 3 | discover_projects · list_schemes · show_build_settings | | 📱 Simulator | 15 | list_simulators · boot_simulator · shutdown_simulator · erase_simulator · session_set_defaults · simulate_location · clear_location · set_appearance · override_status_bar · show_session · clear_session · manage_privacy · send_push_notification · get_app_container · uninstall_app | | 🔨 Build | 8 | build_simulator · build_run_simulator · test_simulator · launch_app · stop_app · clean_derived_data · inspect_xcresult · list_crash_logs | | 📲 Device | 8 | list_devices · build_for_device · build_run_device · test_on_device · install_app_device · launch_app_device · stop_app_device · device_screenshot | | 📋 Logging | 2 | start_log_capture · stop_log_capture | | 👆 UI Automation | 10 | screenshot · inspect_ui · deep_link · tap · swipe · type_text · key_press · long_press · start_recording · stop_recording | | 🧭 Navigation | 6 | load_nav_graph · get_nav_graph · navigate_to · where_am_i · tag_screen · save_nav_graph | | 🐛 Debugging | 8 | debug_attach · debug_detach · debug_add_breakpoint · debug_remove_breakpoint · debug_resume · debug_backtrace · debug_variables · debug_run_command | | 📦 Swift Package | 6 | swift_package_resolve · swift_package_update · swift_package_init · swift_package_clean · swift_package_show_deps · swift_package_dump | | 🔎 Inspection | 2 | read_user_defaults · write_user_default | | ✅ Quality | 2 | lint · accessibility_audit | | ⚙️ Extras | 1 | open_simulator |

---

🚀 Workflows

Build & Test

discover_projects → list_schemes → session_set_defaults → build_simulator → test_simulator → lint

Discover projects, pick a scheme, build for simulator, run tests, lint for style issues.

UI Exploration

build_run_simulator → screenshot → inspect_ui → tap → type_text → screenshot

Build and launch, screenshot the screen, inspect the accessibility tree, interact with elements, verify the result.

Debug Session

debug_attach → debug_add_breakpoint → debug_resume → debug_backtrace → debug_variables → debug_detach

Attach LLDB, set breakpoints, hit them, inspect the stack and variables, detach cleanly.

Navigation

load_nav_graph → get_nav_graph → where_am_i → navigate_to → where_am_i

Load the app's navigation graph, inspect its structure, identify the current screen, navigate to a target, verify arrival. See docs/navigation.md for the full graph schema and authoring guide.

Physical Device

list_devices → session_set_defaults → build_for_device → install_app_device → launch_app_device → device_screenshot

List connected devices, build with code signing, install and launch on hardware, capture a screenshot.

Swift Package Management

swift_package_show_deps → swift_package_resolve → swift_package_update

Inspect the dependency tree, resolve packages, update to latest versions.

---

📥 Installation

Makefile (recommended)

git clone https://github.com/JAManfredi/ios_mcp.git
cd ios_mcp
make install

Installs to /usr/local/bin by default. Use PREFIX=~/.local to install elsewhere.

Homebrew (build from source)

brew install --build-from-source Formula/ios-mcp.rb

Manual

git clone https://github.com/JAManfredi/ios_mcp.git
cd ios_mcp
brew bundle          # optional dependencies (swiftlint, etc.)
swift build -c release --disable-sandbox
cp .build/release/ios-mcp /usr/local/bin/

---

⚙️ MCP Client Configuration

Register as an MCP server with your client. For example:

{
  "mcpServers": {
    "ios-mcp": {
      "command": "/usr/local/bin/ios-mcp"
    }
  }
}

ios-mcp communicates over stdio using the MCP protocol. It works with any MCP-compatible client — add the binary path to your client's server configuration and restart.

---

📋 Requirements

| Dependency | Version | Required | |-----------|---------|----------| | macOS | 14+ | ✅ | | Xcode | 16+ | ✅ | | iOS Simulator runtime | Any installed | ✅ | | Swift | 6.1+ | ✅ | | axe | 0.4.0+ | Optional — UI automation | | SwiftLint | Any | Optional — lint tool | | devicectl (via Xcode) | Xcode 16+ | Optional — physical devices |

---

🧠 Session Defaults

session_set_defaults stores frequently-used values so they don't need to be repeated on every tool call:

• simulator_udid — target simulator
• device_udid — target physical device
• workspace / project — Xcode workspace or project path
• scheme — build scheme
• bundle_id — app bundle identifier
• configuration — Debug / Release

A typical session starts with discover_projects → list_schemes → session_set_defaults, after which tools like build_simulator, test_simulator, and launch_app pick up the context automatically. Use show_session to inspect current defaults and clear_session to reset them.

Some tools auto-set defaults as a side effect:

• show_build_settings → bundle_id
• boot_simulator → simulator_udid
• list_devices → device_udid (when exactly one device is connected)

Session defaults are validated before use — if a simulator is deleted or a path no longer exists, the tool returns a stale_default error instead of silently using invalid state.

---

🔒 Safety

ios-mcp is designed for local development with a security-first posture:

| Feature | Description | |---------|-------------| | No telemetry | No data leaves your machine | | No network access | Communicates only via stdin/stdout JSON-RPC | | Arg-array execution | All subprocess calls use direct argument arrays — never /bin/sh -c | | Secret redaction | Bearer tokens, API keys, signing identities, and provisioning profiles are stripped from output | | LLDB denylist | Dangerous commands (platform shell, memory write, etc.) blocked by default | | Resource locking | Prevents conflicting operations on the same resource | | Session validation | Stale defaults are caught before use |

---

🩺 Doctor

ios-mcp doctor checks your environment for required and optional dependencies:

$ ios-mcp doctor
ios-mcp doctor
==============

[ok] macOS: 15.3.0
[ok] Xcode: /Applications/Xcode.app/Contents/Developer
[ok] Xcode version: 16.2
[ok] Simulator: simctl available
[ok] LLDB: lldb-1600.0.36.3
[ok] axe: 0.4.0 [ok] checksum verified
[ok] devicectl: available (physical device support)
[ok] SwiftLint: /usr/local/bin/swiftlint
[ok] ios-mcp version: 0.1.0

Verdict: SUPPORTED — all checks passed.

[!!] = required (blocks functionality) · [--] = optional (some tools unavailable)

---

🏗 Architecture

| Module | Role | |--------|------| | Core | Tool registry, command execution, session state, concurrency policy, artifact store, redaction, validation, log capture, LLDB sessions, video recording, navigation graph store | | Tools | 71 tool implementations across 13 categories | | IosMcp | Executable entry point — MCP server, ArgumentParser routing, doctor |

See AGENTS.md for contributor guidance including coding conventions, error handling patterns, and detailed type documentation.

---

📄 License

MIT — see LICENSE. Third-party dependency licenses in THIRD_PARTY.md.