axiom xcode mcp
- Repo stars 0
- License MIT
- 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
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @CharlesWiltgen · MIT
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- 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
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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)
- Launching an agent 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 -> When to Use → Routing Logic → 1. Setup/Connection → xcode-mcp-setup → 2. Using Tools & Workflows → xcode-mcp-tools → 3. Tool API Reference → xcode-mcp-ref → Decision Tree
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 -> xcrun mcpbridge · run-agent · devicectl · simctl · xcui · xclog · xcsym · xcprof
body sha256 -> 2f0930d725d6
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)
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?"
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" ·
workspaceIdentifieris required anyway, despite being absent from everyrequiredlist.