158 lines
5.0 KiB
Markdown
158 lines
5.0 KiB
Markdown
# XcodeBuildMCP (iOS)
|
|
|
|
This page focuses on MCP-based Xcode workflows and the XcodeBuildMCP setup.
|
|
|
|
## What XcodeBuildMCP Is (Plain Language)
|
|
XcodeBuildMCP can run build and test tasks without you switching into Xcode for every step. This reduces context switching and makes workflows repeatable.
|
|
|
|
Think of it as a remote control for Xcode build actions. Instead of clicking around in Xcode, you ask the assistant to run the action and report the result.
|
|
|
|
Common uses include:
|
|
+- Run a build for a target or scheme
|
|
+- Run tests and return failures
|
|
+- Capture build output so the assistant can summarize errors
|
|
|
|
### Example Requests
|
|
+- "Use XcodeBuildMCP to build the app and summarize any errors."
|
|
+- "Run tests with XcodeBuildMCP and list the failing tests."
|
|
+- "Build with XcodeBuildMCP and extract the first error message."
|
|
|
|
## What It Can Do (Detailed Examples)
|
|
Below are common tasks and how to ask for them. Adjust the wording to match your project.
|
|
|
|
### Build
|
|
Goal: Run a build and get a short error summary.
|
|
|
|
Example:
|
|
"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."
|
|
|
|
### Unit Tests
|
|
Goal: Run unit tests and list failures.
|
|
|
|
Example:
|
|
"Run unit tests with XcodeBuildMCP and list failing tests with file names."
|
|
|
|
### UI Tests
|
|
Goal: Run UI tests on a known simulator.
|
|
|
|
Example:
|
|
"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."
|
|
|
|
### Screenshots (UI Testing)
|
|
Goal: Trigger a UI test that captures screenshots and then list the generated images.
|
|
|
|
Example:
|
|
"Run the UI test that captures screenshots and list the output paths."
|
|
|
|
### Build Output Parsing
|
|
Goal: Extract the first error for quick diagnosis.
|
|
|
|
Example:
|
|
"Build with XcodeBuildMCP and extract the first error message only."
|
|
|
|
## Xcode 26.3 MCP Setup (Detailed)
|
|
These steps reflect a common setup as of February 2026. Wording may vary slightly in release candidates.
|
|
|
|
### Prerequisites
|
|
+- Xcode 26.3 (RC or full release), opened at least once with your project
|
|
+- VS Code installed (stable or Insiders)
|
|
+- GitHub Copilot extension installed and signed in
|
|
+- Node.js and npm installed (for XcodeBuildMCP)
|
|
|
|
### Step 1: Enable Xcode MCP Server
|
|
+1. Open Xcode.
|
|
+2. Go to Settings.
|
|
+3. Open the Intelligence tab.
|
|
+4. Find the Model Context Protocol section.
|
|
+5. Toggle on Xcode Tools (or Allow external connections).
|
|
|
|
### Step 2: Install And Configure XcodeBuildMCP (Recommended Bridge)
|
|
+Install:
|
|
+
|
|
+```bash
|
|
+npm install -g xcodebuildmcp@latest
|
|
+```
|
|
+
|
|
+Add to VS Code (create or edit .vscode/mcp.json):
|
|
+
|
|
+```json
|
|
+{
|
|
+ "servers": {
|
|
+ "XcodeBuildMCP": {
|
|
+ "command": "npx",
|
|
+ "args": ["-y", "xcodebuildmcp@latest", "mcp"]
|
|
+ }
|
|
+ }
|
|
+}
|
|
+```
|
|
+
|
|
+Restart VS Code or reload the window. Copilot should discover the tools.
|
|
|
|
### Step 3: Optional Native Xcode MCP Bridge
|
|
+Xcode 26.3 includes a native MCP bridge. This exposes Xcode tools directly.
|
|
+
|
|
+Add to VS Code:
|
|
+
|
|
+```json
|
|
+{
|
|
+ "servers": {
|
|
+ "XcodeNative": {
|
|
+ "command": "xcrun",
|
|
+ "args": ["mcpbridge"]
|
|
+ }
|
|
+ }
|
|
+}
|
|
+```
|
|
+
|
|
+### Using MCP In VS Code With Copilot
|
|
+1. Open your iOS project in VS Code.
|
|
+2. Use Copilot Chat in agent mode for multi-step tasks.
|
|
+3. MCP tools appear as slash commands once discovered.
|
|
+
|
|
+Example:
|
|
+"Use XcodeBuildMCP to build and summarize errors. Then suggest fixes."
|
|
|
|
### Tips And Caveats
|
|
+- Xcode must be running (or launchable) for MCP tools to respond.
|
|
+- Native Xcode MCP is often best for previews.
|
|
+- XcodeBuildMCP is often best for heavy builds and automation.
|
|
|
|
## Standardize The Simulator (Avoid Back-And-Forth)
|
|
Pin a simulator name and OS version in your project guidance so the assistant always uses the same target.
|
|
|
|
### Example Agent Guidance
|
|
Add this to your Agents.md (or project instructions):
|
|
|
|
```text
|
|
When running iOS builds or tests, always use XcodeBuildMCP with the iOS simulator "iPhone 17 Pro Max" on iOS 26.2. Do not choose other simulators unless instructed.
|
|
```
|
|
|
|
### Why This Helps
|
|
- Removes ambiguity about which simulator to use
|
|
- Avoids repeated clarifying questions
|
|
- Keeps build outputs consistent across developers
|
|
|
|
### Install And Setup (Official)
|
|
+Follow the official instructions: https://github.com/getsentry/XcodeBuildMCP
|
|
|
|
### References
|
|
+- https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/
|
|
+- https://github.com/cameroncooke/XcodeBuildMCP
|
|
+- https://github.com/getsentry/XcodeBuildMCP
|
|
+- https://code.visualstudio.com/docs/copilot/customization/mcp-servers
|
|
|
|
## Xcode 26.3 And MCP Integration
|
|
+Apple announced that Xcode 26.3 exposes Xcode capabilities through the Model Context Protocol (MCP), which enables compatible agents and tools to interact with Xcode features directly.
|
|
|
|
### What This Means (Plain Language)
|
|
+- Xcode can be controlled by MCP-enabled tools.
|
|
+- Agents can access more of Xcode's capabilities without you manually clicking through the UI.
|
|
|
|
### Example Workflow
|
|
+1. You ask an agent to build the project.
|
|
+2. The agent uses MCP to run the build inside Xcode.
|
|
+3. The agent summarizes errors and suggests fixes.
|
|
|
|
### Source
|
|
+https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/
|