axiom xcode mcp
- Repo stars 0
- Author updated Aug 24, 2026, 06:29 PM
- Author repo Axiom
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @CharlesWiltgen · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
## Cursor MCP Tool Boundary
The `xclog`, `xcsym`, and `xcprof` examples below are reference syntax, not executable commands for Cursor. Map each subcommand to the same-named MCP tool—for example, `xclog launch` to `axiom_xclog_launch`, `xcsym crash` to `axiom_xcsym_crash`, and `xcprof record` to `axiom_xcprof_record`—and preserve its arguments as structured fields. Do not run a bare helper binary. If a required MCP tool is unavailable, stop and report that the Axiom MCP integration is missing; do not fall back to a same-named executable.
## Cursor UI Tool Availability
`xcui` is an external tool and is not bundled with the Cursor plugin; it has no Axiom MCP wrapper. Before UI automation, check `command -v xcui`. If it is absent, AXe fallback is limited to compatible input verbs: `tap`, `slider`, `type`, `swipe`, `drag`, `touch`, `gesture`, `button`, `key`, `key-sequence`, `key-combo`, and `screenshot`. Then check `command -v axe` before that fallback and handle `DEVELOPER_DIR` explicitly if AXe reports a SimulatorKit loading error. AXe cannot replace `wait`, `assert`, `a11y`, `dialog`, `voiceover`, `resize`, or `doctor`. If neither tool is available, stop UI automation, explain the external setup requirement, and continue only with non-UI simulator and log checks. If AXe exists but the requested workflow requires an xcui-only capability, stop that UI workflow and report the limitation.
# Xcode MCP
**You MUST use this skill for ANY Xcode MCP interaction — setup, tool usage, workflow patterns, or troubleshooting.**
Xcode ships an MCP server exposing IDE tools to external AI clients. `xcrun mcpbridge` is the stdio transport clients register, available since Xcode 26.3. Xcode 27 adds an explicit "Allow external agents to use Xcode tools" gate, the `run-agent` launch path, an agent-extension model (custom MCP servers, skills, plug-ins), and a headless server. This skill suite covers setup, tool reference, workflow patterns, and troubleshooting.
**On Xcode 26.x, mcpbridge requires a running Xcode with a project open.** If that's a liability, the device/simulator half of these operations has a fully Xcode-independent CLI path: `devicectl` + `simctl` + Axiom's `xcui`/`xclog`/`xcsym`/`xcprof`. See `axiom-tools (skills/device-control-ref.md)`.
**That constraint is gone on Xcode 27.** `xcrun mcp-server` runs the tool service with Xcode.app closed — `sudo xcrun mcp-server enable`, then `start` and `open <path>`. Clients still register `xcrun mcpbridge`; the bridge is the transport, `mcp-server` is the service. Apple's tool schemas describe `workspaceIdentifier` as "used in headless mode", so headless is a supported model rather than a workaround.
Choose between MCP and the CLI tools (`devicectl`, `simctl`, and Axiom's `xcui`/`xclog`/`xcsym`/`xcprof`) on **capability, not uptime**. `xcui` asserts, waits, toggles accessibility settings, and computes VoiceOver announcements, and none of them need `sudo` — which still matters in CI, where the headless server's sudo opt-in may not be available. The IDE-authoring tools (build state, render previews) remain MCP-only; `xcodebuild` builds and tests but does not render previews.
## When to Use
Use this skill when:
- Setting up Xcode MCP for the first time
- Configuring `xcrun mcpbridge` for any MCP client
- Using any Xcode MCP tool (file ops, build, test, preview)
- Building, testing, or previewing via MCP tools
- Troubleshooting mcpbridge connection issues
- Workspace targeting questions
- Permission dialog confusion
- Driving simulator input with AXe (`tap`/`type`/`swipe`) -> read `skills/axe-ref.md`
## Routing Logic
### 1. Setup/Connection → **xcode-mcp-setup**
**Triggers**:
- First-time Xcode MCP setup
- Client-specific config (Claude Code, Cursor, Codex, VS Code, Gemini CLI)
- Connection errors ("Connection refused", "No workspaces are currently open.")
- Permission dialog confusion
- Multi-Xcode targeting (`MCP_XCODE_PID`)
- Schema compliance issues with strict clients
- Giving external agents access to Xcode (Intelligence settings gate)
- Delegate to the `an` subagent via Xcode config (`xcrun mcpbridge run-agent`)
- Exporting Xcode's skill bundles (`xcrun agent skills export`)
- Extending Xcode's agent (per-agent config files, MCP servers, plug-ins)
**Read**: `skills/xcode-mcp-setup.md`
---
### 2. Using Tools & Workflows → **xcode-mcp-tools**
**Triggers**:
- How to build/test/preview via MCP
- Workflow patterns (BuildFix loop, TestFix loop)
- Tool gotchas and anti-patterns
- Workspace targeting strategy; headless bootstrap (open or create a workspace)
- When to use MCP tools vs CLI (`xcodebuild`)
- Destructive operation safety (`XcodeRM`, `XcodeMV`)
**Read**: `skills/xcode-mcp-tools.md`
---
### 3. Tool API Reference → **xcode-mcp-ref**
**Triggers**:
- Specific tool parameters and schemas
- Input/output format for a tool
- "How does XcodeGrep work?"
- "What params does BuildProject take?"
- Tool category listing
**Read**: `skills/xcode-mcp-ref.md`
---
## Decision Tree
```dot
digraph xcode_mcp_router {
rankdir=TB;
"User has Xcode MCP question" [shape=ellipse];
"Setup or connection?" [shape=diamond];
"Using tools or workflows?" [shape=diamond];
"Need specific tool params?" [shape=diamond];
"xcode-mcp-setup" [shape=box];
"xcode-mcp-tools" [shape=box];
"xcode-mcp-ref" [shape=box];
"User has Xcode MCP question" -> "Setup or connection?";
"Setup or connection?" -> "xcode-mcp-setup" [label="yes"];
"Setup or connection?" -> "Using tools or workflows?" [label="no"];
"Using tools or workflows?" -> "xcode-mcp-tools" [label="yes"];
"Using tools or workflows?" -> "Need specific tool params?" [label="no"];
"Need specific tool params?" -> "xcode-mcp-ref" [label="yes"];
"Need specific tool params?" -> "xcode-mcp-tools" [label="general question"];
}
```
## Anti-Rationalization
| Thought | Reality |
|---------|---------|
| "I'll just use xcodebuild directly" | MCP gives IDE state, filtered compiler diagnostics, and rendered previews that CLI doesn't expose |
| "I already know how to set up MCP" | Client configs differ. Permission dialog behavior is specific. Check setup skill. |
| "I can figure out the tool params" | Tool schemas have required fields and gotchas. Check ref skill. |
| "One workspace is open, so I can skip the identifier" | `workspaceIdentifier` is required anyway, despite being absent from every `required` list. |
| "This is just file reading, I'll use Read tool" | XcodeRead sees Xcode's project view including generated files and resolved packages |
## Conflict Resolution (vs Other Routers)
| Domain | Owner | Why |
|--------|-------|-----|
| MCP-specific interaction (mcpbridge, mcp-server, MCP tools, workspace identifiers) | **axiom-xcode-mcp** | MCP protocol and tool-specific |
| Xcode environment (Derived Data, zombie processes, simulators) | **axiom-build** | Environment diagnostics, not MCP |
| Apple's bundled documentation (for-LLM guides/diagnostics) | **axiom-apple-docs** | Bundled docs, not MCP tool |
| `DocumentationSearch` MCP tool usage specifically | **axiom-xcode-mcp** | MCP tool invocation |
| Build failures diagnosed via CLI | **axiom-build** | Traditional build debugging |
| Build failures diagnosed via MCP tools | **axiom-xcode-mcp** | MCP workflow patterns |
## Example Invocations
User: "How do I set up Xcode MCP with Claude Code?"
-> Read: `skills/xcode-mcp-setup.md`
User: "How do I build my project using MCP tools?"
-> Read: `skills/xcode-mcp-tools.md`
User: "What parameters does BuildProject take?"
-> Read: `skills/xcode-mcp-ref.md`
User: "My mcpbridge connection keeps failing"
-> Read: `skills/xcode-mcp-setup.md`
User: "How do I target a specific workspace?" / "How do I run this without Xcode open?"
-> Read: `skills/xcode-mcp-tools.md`
User: "Can I render SwiftUI previews via MCP?"
-> Read: `skills/xcode-mcp-tools.md` (workflow), then `skills/xcode-mcp-ref.md` (params)
User: "Cursor can't parse Xcode's MCP responses"
-> Read: `skills/xcode-mcp-setup.md` (schema compliance section)
## Resources
**Skills**: skills/xcode-mcp-setup.md, skills/xcode-mcp-tools.md, skills/xcode-mcp-ref.md, skills/axe-ref.md
Sections and files
Listed in source order.
sections -> Cursor MCP Tool Boundary → Cursor UI Tool Availability → When to Use → Routing Logic → 1. Setup/Connection → xcode-mcp-setup → 2. Using Tools & Workflows → xcode-mcp-tools
terms -> On Xcode 26.x, mcpbridge requires a running Xcode with a project open. · That constraint is gone on Xcode 27. · capability, not uptime · xcode-mcp-setup · Triggers · Read · xcode-mcp-tools · xcode-mcp-ref
files/cmd -> xclog · xcsym · xcprof · xclog launch · axiom_xclog_launch · xcsym crash · axiom_xcsym_crash · xcprof record
body sha256 -> ad5a571bdfba
Cursor MCP Tool Boundary
The
xclog,xcsym, andxcprofexamples below are reference syntax, not executable commands for Cursor. Map each subcommand to the same-named MCP tool—for example,xclog launchtoaxiom_xclog_launch,xcsym crashtoaxiom_xcsym_crash, andxcprof recordtoaxiom_xcprof_record—and preserve its arguments as structured fields. Do not run a bare helper binary. If a required MCP tool is unavailable, stop and report that the Axiom MCP integration is missing; do not fall back to a same-named executable.Cursor UI Tool Availability
xcuiis an external tool and is not bundled with the Cursor plugin; it has no Axiom MCP wrapper. Before UI automation, checkcommand -v xcui.When to Use
Use this skill when: Setting up Xcode MCP for the first time Configuring
xcrun mcpbridgefor any MCP client Using any Xcode MCP tool (file ops, build, test, preview) Building, testing, or previewing via MCP tools1. Setup/Connection → xcode-mcp-setup
Triggers: First-time Xcode MCP setup Client-specific config (Claude Code, Cursor, Codex, VS Code, Gemini CLI) Connection errors ("Connection refused", "No workspaces are currently open.") Permission dialog confusion
2. Using Tools & Workflows → xcode-mcp-tools
Triggers: How to build/test/preview via MCP Workflow patterns (BuildFix loop, TestFix loop) Tool gotchas and anti-patterns Workspace targeting strategy; headless bootstrap (open or create a workspace)