xcforge

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

109 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.git
cd xcforge && swift build -c release
cp .build/release/XCForgeCLI /usr/local/bin/xcforge

Uninstall

Homebrew

brew uninstall xcforge
brew 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 includes a Claude Code skill that loads the full tool reference into context when you're working on iOS tasks. Install it globally with:

npx skills justinthevoid/xcforge

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, 109 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: