mbrucedogs/ai-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d1e2835b0
ai-docs/docs/ai/ios/ios-xcodebuildmcp-vscode.md
Matt Bruce 8533890d2c refactored filesystem 
Signed-off-by: Matt Bruce <matt.bruce1@toyota.com>
2026-02-12 16:33:53 -06:00

3.9 KiB
Raw Blame History

XcodeBuildMCP for iOS in VS Code

You are here: AI Docs Home > 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

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.

Example (Toyota):

schemaVersion: 1
sessionDefaults:
	workspacePath: ./OneApp.xcworkspace
	scheme: ToyotaOneApp
	configuration: Debug
	simulatorName: iPhone 17 Pro Max
	simulatorId: <SIMULATOR_UDID>
	useLatestOS: true

Notes:

  • Use either simulatorName or simulatorId. If both are set, simulatorId takes precedence.
  • The simulator must be installed and booted before running build/run.

3. Configure MCP in VS Code

  • Ensure .vscode/mcp.json exists:
{
	"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

Next Steps