xcode-studio-mcp
Unified MCP server for Xcode + iOS Simulator — build, deploy, screenshot, and interact with your iOS app from Claude Code, Cursor, or any MCP client.
Built in Swift. Single binary. No Node/Python runtime required.
Why This Exists
Today you need 2-3 separate tools to do the full iOS dev loop with an AI agent. xcode-studio-mcp combines them into one:
Write code → Build → Deploy to Simulator → Screenshot → Tap/Type → Verify
Tools
| Tool | Description |
|---|---|
xcode_build |
Build an Xcode project with structured error output (file, line, column, severity, message) |
xcode_run |
Build and launch an app in the iOS Simulator |
simulator_screenshot |
Capture the Simulator screen as a PNG image |
simulator_tap |
Tap at x,y coordinates on the Simulator screen |
simulator_type |
Type text into the currently focused field |
simulator_describe |
Get the accessibility tree of the current screen (JSON) |
Tool Parameters
xcode_build
| Parameter | Required | Description |
|---|---|---|
project_path |
Yes | Path to Xcode project directory, .xcodeproj, or .xcworkspace |
scheme |
No | Build scheme (auto-detected if omitted) |
configuration |
No | Debug (default) or Release |
destination |
No | Build destination (defaults to booted simulator) |
xcode_run
| Parameter | Required | Description |
|---|---|---|
project_path |
Yes | Path to Xcode project |
bundle_identifier |
Yes | App bundle ID (e.g. com.example.MyApp) |
scheme |
No | Build scheme (auto-detected) |
simulator_udid |
No | Target simulator (defaults to booted) |
simulator_screenshot
| Parameter | Required | Description |
|---|---|---|
simulator_udid |
No | Target simulator (defaults to booted) |
simulator_tap
| Parameter | Required | Description |
|---|---|---|
x |
Yes | X coordinate |
y |
Yes | Y coordinate |
duration |
No | Hold duration in seconds (for long press) |
simulator_udid |
No | Target simulator |
simulator_type
| Parameter | Required | Description |
|---|---|---|
text |
Yes | Text to type |
simulator_udid |
No | Target simulator |
simulator_describe
| Parameter | Required | Description |
|---|---|---|
simulator_udid |
No | Target simulator |
Quick Start
Prerequisites
- macOS with Xcode installed
- For UI interaction tools (
tap,type,describe):brew tap facebook/fb && brew install idb-companion pip3 install fb-idb
Build
git clone https://github.com/kevinswint/xcode-studio-mcp.git
cd xcode-studio-mcp
swift build -c release
Configure Claude Code
Add to your Claude Code MCP settings:
{
"mcpServers": {
"xcode-studio-mcp": {
"command": "/path/to/xcode-studio-mcp/.build/release/XcodeStudioMCP"
}
}
}
Example Workflow
You: Build and run my app at ~/Projects/MyApp
Claude: [calls xcode_build] Build succeeded with 0 errors
[calls xcode_run] App launched (PID 12345)
[calls simulator_screenshot] Here's what the app looks like...
[calls simulator_describe] I can see a "Sign In" button and email/password fields
[calls simulator_tap] Tapped the email field
[calls simulator_type] Typed "[email protected]"
[calls simulator_screenshot] Here's the current state...
Architecture
┌─────────────────────────────┐
│ MCP Protocol Layer │ stdio transport (Swift MCP SDK)
├─────────────────────────────┤
│ Tool Implementations │ 6 tools, structured error output
├──────────┬──────────────────┤
│ xcodebuild│ simctl │ idb │ native process calls
│ wrapper │ wrapper │ CLI │
└──────────┴──────────┴──────┘
Built in Swift with zero Node/Python runtime dependencies (idb CLI is only needed for UI interaction tools).
Roadmap
- v0.1 (current): Core build + simulator tools
- v1.0: Semantic UI navigation ("tap the Sign In button"), visual diff, Xcode project file manipulation, compound operations, SwiftUI preview capture
Related Projects
| Project | What It Does | Difference |
|---|---|---|
| XcodeBuildMCP | Build + test only | No simulator UI interaction |
| mobile-mcp | Cross-platform simulator UI | No Xcode build support |
| ios-simulator-mcp | Simulator via IDB | No build, depends on IDB for everything |
xcode-studio-mcp combines build and interact into a single server.
Contributing
PRs welcome. The codebase is ~750 lines of Swift organized into Tools, Services, and Models.
License
MIT
