xcforge - iOS MCP Server & CLI

xcforge

[xcforge]

[License: MIT] [Platform] [Swift 6.0] [MCP] [Homebrew] [GitHub release] [PRs Welcome]

An MCP server and CLI for iOS development — build, test, automate, and diagnose from any AI agent or terminal.

104 MCP tools. 19 CLI command groups. Single native binary (~8 MB stripped, ~18 MB with debug symbols). Zero external runtime dependencies.

Install

Homebrew (recommended)

brew tap justinthevoid/tap && brew install xcforge

Claude Code (one-liner)

claude mcp add xcforge -- xcforge

This registers xcforge as an MCP server in your current project. Run it after installing via Homebrew.

From source

git clone https://github.com/justinthevoid/xcforge.gitcd xcforge && swift build -c releasecp .build/release/XCForgeCLI /usr/local/bin/xcforge

Uninstall

Homebrew

brew uninstall xcforgebrew untap justinthevoid/tap   # optional: remove the tap

From source

rm /usr/local/bin/xcforge

Remove MCP configuration

After uninstalling the binary, remove the "xcforge" entry from your MCP client config file (see Configure for file locations).

For Claude Code:

claude mcp remove xcforge

Configure

Add xcforge to your MCP client. Each client has a different config format and file location.

Claude Code

The fastest way is the CLI command shown above under Install. To configure manually, add to .mcp.json in your project root (or ~/.claude/.mcp.json for global):

{  "mcpServers": {    "xcforge": {      "command": "xcforge",      "args": [],      "type": "stdio"    }  }}

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json

{  "mcpServers": {    "xcforge": {      "command": "/opt/homebrew/bin/xcforge",      "args": []    }  }}

Note: Claude Desktop does not inherit your shell PATH. Use the full Homebrew path — /opt/homebrew/bin/xcforge on Apple Silicon, /usr/local/bin/xcforge on Intel.

Cursor

File: .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global)

{  "mcpServers": {    "xcforge": {      "command": "/opt/homebrew/bin/xcforge",      "args": []    }  }}

Note: Same PATH caveat as Claude Desktop — use the absolute path. Restart Cursor after changes.

VS Code (GitHub Copilot)

File: .vscode/mcp.json in your project root

{  "servers": {    "xcforge": {      "command": "xcforge",      "args": [],      "type": "stdio"    }  }}

Note: VS Code uses "servers" not "mcpServers". Requires the GitHub Copilot extension with agent mode enabled. VS Code typically resolves PATH from your shell, so the bare command works.

Windsurf

File: ~/.codeium/windsurf/mcp_config.json

{  "mcpServers": {    "xcforge": {      "command": "/opt/homebrew/bin/xcforge",      "args": []    }  }}

Note: Full path recommended. Restart Windsurf after editing.

Zed

File: ~/.config/zed/settings.json (or .zed/settings.json per-project)

{  "context_servers": {    "xcforge": {      "command": {        "path": "/opt/homebrew/bin/xcforge",        "args": []      },      "settings": {}    }  }}

Note: Zed uses "context_servers" with a nested "command.path" — different from every other client.

Config quick reference

Claude Code Skill

xcforge ships an agent skill: the tool reference an agent loads when it works on iOS tasks. The binary carries it, so installing it needs nothing else:

xcforge skill install            # this repo: .claude/skills/xcforge (commit it to share with the team)xcforge skill install --global   # every project: ~/.claude/skills/xcforgexcforge skill install --dir <skills-dir>      # any other agent's skills directoryxcforge skill status             # where it's installed and whether it matches this xcforgexcforge skill show references/test-tools.md   # print one file without installing

Re-run xcforge skill install after upgrading xcforge to refresh the copy; only changed files are rewritten. It won't overwrite an xcforge skill directory it didn't create unless you pass --force. xcforge skill uninstall removes it.

Once installed, Claude will automatically load the right reference files when you use xcforge tools — exact parameters, return values, and usage patterns for each category (build, test, simulator, UI automation, logs, LLDB, diagnosis, and more).

Two Modes, Same Tools

xcforge                          # MCP server (stdio JSON-RPC, 104 tools)xcforge build --scheme MyApp     # CLI mode (19 command groups)

Every tool available over MCP has a matching CLI command. Every CLI command supports --json.

Tools Overview

Key Capabilities

Structured Test Results

Test output is parsed from .xcresult bundles — the structured format Xcode generates internally — not from raw xcodebuild stdout/stderr.

A single test_sim call returns: pass/fail counts, failure messages with source location, exported failure screenshots, and the xcresult path for deeper inspection via test_failures or test_coverage.

Fast Screenshots

The screenshot tool reads the simulator framebuffer via CoreSimulator's IOSurface API, falling back to ScreenCaptureKit, then simctl. Typical latency is ~300ms.

UI Automation Without Appium

xcforge communicates directly with WebDriverAgent over HTTP and supplements it with a native Accessibility API bridge (AXPBridge). This means:

• find_element with scroll: true auto-scrolls using 3 fallback strategies
• handle_alert searches across SpringBoard, ContactsUI, and the active app — accept_all clears multiple permission dialogs in one call
• drag_and_drop works with element IDs, not just coordinates
• get_source returns the full view hierarchy in ~20ms

Topic-Filtered Logs

start_log_capture streams os_log through 4 filter layers:

1. Noise exclusion — strips 15 known noisy processes at the stream level
2. Capture modes — smart (broad + topic-ready), app (tight, auto-detected bundle), verbose
3. Topic filtering — read_logs classifies lines into 8 topics (app, crashes, network, lifecycle, springboard, widgets, background, system) and shows only app + crashes by default
4. Deduplication — collapses repeated lines

The response includes a topic menu with counts, so the agent can pull in specific topics on demand without re-querying.

Interactive LLDB Debugger

8 tools for attaching LLDB to running simulator processes, setting breakpoints, inspecting variables, viewing stack traces, and stepping through code. Sessions persist for 30 minutes, so you can attach once and run multiple debugging operations. CLI commands are one-shot (attach → operation → detach). Includes:

• Session management: lldb_attach (by bundle ID or PID), lldb_detach
• Breakpoints: set by file+line or function name, remove by ID
• Inspection: evaluate expressions at the current frame, view stack traces
• Execution control: continue, step over, step into, step out (with 10-second timeout)
• Raw passthrough: run arbitrary LLDB commands

Use alongside logs and screenshots for systematic root-cause analysis.

Diagnosis Workflows

10 tools (off by default: turn them on with XCFORGE_TOOL_GROUPS=+diagnose or tool_groups) that chain together into structured diagnostic pipelines — start a session, build, launch, capture runtime signals, collect evidence (screenshots, logs, accessibility state), compare against previous runs, and verify fixes. Designed for agents to systematically debug issues across multiple iterations.

Physical Device Support

Tools wrapping Apple's devicectl for real devices: list connected devices, install, launch (with deep links and environment variables) and terminate apps, and take screenshots. xcforge wda start --device <udid> --team <TEAM> (MCP wda_start) builds, signs and starts WebDriverAgent on the device so the UI automation tools work there too; see device-tools.md.

CLI Examples

xcforge init                                     # Scaffold a committed .xcforge.yaml (repo defaults)xcforge build                                    # Build (auto-detects project, scheme, sim)xcforge build compile --scheme MyApp             # Fast compile-only check (~5s)xcforge build --scheme MyApp --simulator "iPhone 16 Pro"xcforge test --scheme MyApp --json               # Run tests, JSON outputxcforge test --for agent                         # Agent-optimized slim JSONxcforge test --gate                              # Subtract known-failures.yamlxcforge test rerun-failed                        # Replay last run's failuresxcforge test plan inspect --plan AllTests        # Inspect .xctestplanxcforge build-test --env BLESS_BASELINE=1        # Inject env var into test processxcforge test failures --xcresult /path/to.xcresultxcforge test coverage --min-coverage 80xcforge bless --baseline login --tests "UITests/LoginTests"  # Baseline+test+diff in one callxcforge sim list                                 # List simulatorsxcforge sim boot "iPhone 16 Pro"xcforge sim info                                 # Booted simulator screen size and scalexcforge ui find --aid "loginButton"              # Find by accessibility IDxcforge ui tap --element el-0                    # Tap element at point coordinatesxcforge ui tap-pixel --x 750 --y 1334            # Tap at pixel coordinatesxcforge screenshot                               # Screenshot to stdoutxcforge screenshot --grid --output /tmp/x.png    # Screenshot with point-coordinate gridxcforge pose Settings                            # Build, install, launch to a screenxcforge log start                                # Start log capturexcforge log read --include network               # Read with topic filterxcforge spm resolve                              # Resolve packagesxcforge device list                              # Connected physical devicesxcforge debug attach --bundle-id com.example.App    # Attach debuggerxcforge debug breakpoint set --bundle-id com.example.App --file ViewController.swift --line 42xcforge debug inspect --bundle-id com.example.App --expression "self.count"xcforge debug backtrace --bundle-id com.example.App # Show stack tracexcforge debug continue --bundle-id com.example.App --mode step-overxcforge diagnose start --scheme MyApp            # Start diagnosis session

Alternatives

There are several iOS-focused MCP servers worth knowing about:

• XcodeBuildMCP — The most popular iOS MCP server. Backed by Sentry. Covers build, test, and simulator management well. If you only need build/run workflows, it's a solid choice.
• ios-simulator-mcp — Focused on simulator UI interaction — screenshots, taps, swipes, accessibility tree. Good if you only need simulator automation.
• xcode-mcp-server — Early MCP server for Xcode project management. Basic integration — no simulator automation, testing, or device support.
• iosef — Agent-optimized simulator CLI with clean ergonomics. Narrow scope but thoughtful design. Swift native.
• Appium MCP — Cross-platform (iOS + Android) via the Appium ecosystem. Requires Node.js + Java + Appium server — heavier dependency chain.

Where xcforge fits: It combines fast compile checks, build, test, pixel-accurate UI automation, screenshot grids, screen-targeted launch, log analysis, visual regression, device support, SPM, accessibility auditing, and multi-step diagnosis in a single zero-dependency binary. The trade-off is iOS-only — no Android, watchOS, or visionOS.

UI Automation Setup

UI automation tools require a WebDriverAgent (WDA) backend running on the simulator. xcforge manages the WDA connection automatically — you just need to point it at a WDA project.

xcforge tries two backends in order:

1. xcforgeWDA (preferred) — xcforge's own WDA fork (com.xcforge.wda.runner). Auto-built and deployed when XCFORGE_WDA_DIR is set.
2. Original WebDriverAgent (fallback) — Facebook/Appium's WDA. Picked up automatically if WDA is already running on port 8100.

Quick setup

Clone appium/WebDriverAgent, rename the project and scheme for xcforge, then set XCFORGE_WDA_DIR:

git clone https://github.com/appium/WebDriverAgent.git xcforgeWDA
# Copy project with xcforge name and remap bundle IDcp -r xcforgeWDA/WebDriverAgent.xcodeproj xcforgeWDA/xcforgeWDA.xcodeprojsed -i '' 's/com\.facebook\.WebDriverAgentRunner/com.xcforge.wda.runner/g' \  xcforgeWDA/xcforgeWDA.xcodeproj/project.pbxproj
# Add xcforgeWDARunner schemecp xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/WebDriverAgentRunner.xcscheme \   xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcschemesed -i '' 's/WebDriverAgent\.xcodeproj/xcforgeWDA.xcodeproj/g' \  xcforgeWDA/xcforgeWDA.xcodeproj/xcshareddata/xcschemes/xcforgeWDARunner.xcscheme

Then add XCFORGE_WDA_DIR to your MCP config:

{  "mcpServers": {    "xcforge": {      "command": "xcforge",      "env": {        "XCFORGE_WDA_DIR": "/path/to/xcforgeWDA"      }    }  }}

xcforge builds and deploys WDA automatically on the first UI tool call on a simulator (~30–60s on first run, instant thereafter). For a physical device run xcforge wda start --device <udid> --team <TEAM> (MCP wda_start) first, with the device unlocked and Settings > Developer > Enable UI Automation on. See the full UI Automation Setup guide for alternative configurations, custom ports, and troubleshooting.

Requirements

• macOS 13+
• Xcode 15+
• Swift 6.0+ (source builds only)
• WebDriverAgent (UI automation only — see UI Automation Setup)

Web Baseline (Story 1.1)

The Web workspace is isolated under Web/ and uses Astro Starlight plus Svelte with Bun-only package/script usage and Biome-only lint/format checks.

cd Webbun installbun run typecheckbun run lintbun run validate

Local route assumptions after bun run dev:

• Marketing route: http://localhost:4321/
• Docs route: http://localhost:4321/docs
• Docs depth route: http://localhost:4321/docs/getting-started

If setup fails, run:

cd Webbun run doctor

Remediation steps are documented in Web/README.md.

Support

If xcforge saves you time, consider supporting development:

[Buy Me a Coffee] [Ko-fi] [GitHub Sponsors]

License

MIT — see LICENSE.

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.