# Ios Mcp

> MCP server for the full iOS development lifecycle — 55 tools for building, testing, debugging, UI automation, and more. Native Swift binary.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jamanfredi-ios-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JAManfredi](https://agentstack.voostack.com/s/jamanfredi)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JAManfredi](https://github.com/JAManfredi)
- **Source:** https://github.com/JAManfredi/ios_mcp

## Install

```sh
agentstack add mcp-jamanfredi-ios-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
# 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](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)

```bash
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)

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

### Manual

```bash
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:

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

ios-mcp communicates over **stdio** using the [MCP protocol](https://modelcontextprotocol.io/). 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](https://github.com/cameroncooke/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](AGENTS.md) for contributor guidance including coding conventions, error handling patterns, and detailed type documentation.

---

## 📄 License

MIT — see [LICENSE](LICENSE). Third-party dependency licenses in [THIRD_PARTY.md](THIRD_PARTY.md).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JAManfredi](https://github.com/JAManfredi)
- **Source:** [JAManfredi/ios_mcp](https://github.com/JAManfredi/ios_mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jamanfredi-ios-mcp
- Seller: https://agentstack.voostack.com/s/jamanfredi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.