An MCP server for the iOS development lifecycle — 71 tools for project discovery, simulator & device management, building, testing, UI automation, debugging, navigation, package management, and quality checks. Works with any MCP-compatible client.

---

💡 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.