# XcodeBuildMCP for iOS in VS Code

You are here: [AI Docs Home](../index.md) > XcodeBuildMCP for iOS in VS Code

## Contents
- Overview
- Requirements
- One-time Repo Setup
- XcodeBuildMCP Installation & Configuration
- Using XcodeBuildMCP in Copilot Chat
- Common Actions & Prompts
- Troubleshooting
- References
- Next Steps

---

## Overview

XcodeBuildMCP lets you run Xcode build and test tasks from within VS Code, using agent workflows and Copilot Chat. This reduces context switching and makes iOS automation repeatable.

---

## Requirements

- macOS with Xcode installed (includes iOS Simulator)
- VS Code with GitHub Copilot Chat enabled
- MCP tools configured in VS Code (repo includes .vscode/mcp.json)
- Node.js 18+ (required by the MCP host)
- This repo opened in VS Code (workspace root)

Optional but commonly needed for successful builds:
- Ruby + Bundler
- CocoaPods
- Flutter + FVM (if working on the Flutter module)

---

## One-time Repo Setup

Run the standard project setup so builds succeed:

1. `./scripts/setup.sh`
2. `bundle exec pod install`
3. If using Flutter: `cd ../oneappmodule-2.0/apps/oneapp && fvm flutter pub get`

---

## XcodeBuildMCP Installation & Configuration

### 1. Install XcodeBuildMCP

```bash
brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp
```


### 2. Configure XcodeBuildMCP

- The repo should include `.xcodebuildmcp/config.yaml`. Make sure it points to the correct workspace, scheme, and simulator.
- [What is config.yaml? See reference and sample.](xcodebuildmcp-config.yaml.md)

### 3. Configure MCP in VS Code

- Ensure `.vscode/mcp.json` exists:

```json
{
	"servers": {
		"XcodeBuildMCP": {
			"command": "xcodebuildmcp",
			"args": ["mcp"]
		}
	}
}
```

- Restart VS Code or reload the window. Copilot should discover the tools.

---

## Using XcodeBuildMCP in Copilot Chat

From Copilot Chat, you can ask to build and run via XcodeBuildMCP. Example prompts:

- "build and run ToyotaOneApp on the iPhone 17 Pro Max simulator"
- "launch ToyotaOneApp without building (use the existing build)"
- "take a screenshot of the home screen"

Common tool actions the agent will use:
- list_devices, list_schemes
- session_set_defaults
- build_run_sim
- launch_app_sim (no build)
- screenshot

---

## Common Actions & Prompts

- **Build:**  
	"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."

- **Unit Tests:**  
	"Run unit tests with XcodeBuildMCP and list failing tests with file names."

- **UI Tests:**  
	"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."

- **Screenshots:**  
	"Run the UI test that captures screenshots and list the output paths."

- **Run without building:**  
	"launch ToyotaOneApp without building"

- **Home screen screenshot (example flow):**
	1. "launch ToyotaOneApp without building"
	2. Wait for the app to load the home screen
	3. "take a screenshot of the home screen"

---

## Troubleshooting

- **Build DB locked:** another build is running. Stop it and retry.
- **Wrong scheme or workspace:** confirm in `.xcodebuildmcp/config.yaml`.
- **Simulator not found:** install/boot the simulator in Xcode or Simulator.app.
- If MCP tools are not available in VS Code, confirm `.vscode/mcp.json` is present and enabled.

---

## References

- https://github.com/getsentry/XcodeBuildMCP
- https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-agentic-coding/
- https://code.visualstudio.com/docs/copilot/customization/mcp-servers

---

## Next Steps

- For iOS setup basics, read [iOS Setup](ios.md).
- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).