XcodeMCP acts as a smart bridge that allows AI assistants to interact directly with the Xcode development environment on macOS. In simple terms, it gives an AI the ability to "sit at the keyboard" and control the actual Xcode application—opening projects, clicking the build button, and running apps or tests just like a human developer. This makes it possible for a developer to ask an AI to not only write code but also verify that the code actually compiles and runs correctly within their specific local environment. Beneath the surface, this tool uses JavaScript for Automation (JXA) to command the Xcode interface directly, rather than relying strictly on background command-line utilities. This approach provides a high degree of control, allowing the server to manage workspaces, switch between build schemes, and navigate to specific lines of code. To ensure the AI gets useful feedback, the server integrates with tools like XCLogParser to translate messy build logs into precise, actionable error reports. It also includes a robust CLI for manual troubleshooting and environment validation to ensure everything is running smoothly before the AI takes over. For advanced debugging and automated testing, XcodeMCP offers powerful features for analyzing test results. It can dive into `.xcresult` files to extract console logs, failure screenshots, and even full UI hierarchies from the moment a test failed. To make this data manageable for AI models, it compresses complex UI structures into a specialized, token-efficient format that reduces size by over 75% while keeping all the vital metadata. This level of detail allows an AI agent to "see" exactly what was happening in the app's interface during a failure, making it an essential tool for automated UI testing and complex bug fixing.
Category: Developer Tools & Code Intelligence
Tags: automation, debugging, ios, macos, testing, xcode
bash brew install xclogparser Install Options: - Run directly via npx: bash npx -y xcodemcp@latest - Install globally via npm: bash npm install -g xcodemcp ---json { "mcpServers": { "xcodemcp": { "command": "npx", "args": ["-y", "xcodemcp@latest"], "env": { "XCODE_MCP_PREFERRED_SCHEME": "YourSchemeName", "XCODE_MCP_PREFERRED_XCODEPROJ": "YourProject.xcodeproj" } } } }bash claude mcp add-json XcodeMCP '{ "command": "npx", "args": ["-y", "xcodemcp@latest"], "env": { } }'LOG_LEVEL | Controls verbosity (SILENT, ERROR, WARN, INFO, DEBUG) | | XCODEMCP_LOG_FILE | Path to save log files (e.g., ~/Library/Logs/xcodemcp.log) | | XCODE_MCP_PREFERRED_SCHEME | Default scheme to use if none is provided in a command | | XCODE_MCP_PREFERRED_XCODEPROJ | Default project file to use | ---xcode_open_project: Open projects and workspaces. - xcode_get_workspace_info: Get workspace status and details. - xcode_get_projects: List projects in a workspace. - xcode_open_file: Open files with optional line numbers. Build Operations: - xcode_build: Build with detailed error parsing. - xcode_clean: Clean build artifacts. - xcode_test: Run tests. - xcode_build_and_run: Build and run the active scheme. - xcode_debug: Start a debugging session. - xcode_stop: Stop the current operation. Configuration & Diagnostics: - xcode_get_schemes: List available schemes. - xcode_set_active_scheme: Switch the active scheme. - xcode_get_run_destinations: List simulators and devices. - xcode_health_check: Environment validation and troubleshooting. XCResult Analysis (Test Result Debugging): - xcresult_browse: Navigate through test hierarchies and analyze failures. - xcresult_summary: Get quick overview statistics (pass rates, duration). - xcresult_get_screenshot: Extract screenshots from test failures. - xcresult_get_ui_hierarchy: Get UI hierarchies as AI-readable JSON. - xcresult_list_attachments: List all attachments (videos, logs) for a test. ---MyApp.xcodeproj using the MyApp scheme." - Run Tests: "Run all tests and show me a summary of any failures." - Debug UI: "Get the UI hierarchy for the failed test testLoginFlow so we can see why the button wasn't found." - Open File: "Open ViewController.swift at line 42 in Xcode." CLI Usage Example: If installed globally, you can use the xcodecontrol command: bash xcodecontrol build --xcodeproj MyApp.xcodeproj --scheme MyAppXCLogParser. The AI can see the exact line number of a failure, modify the file, and immediately run xcode_build again to verify the fix without the developer leaving the chat interface. Example: 1. The AI runs xcode_build and detects a "Missing argument" error in UserView.swift:42. 2. The AI reads the file, applies the fix, and runs xcode_build again. 3. The AI reports: "Build successful. I've also run xcode_test and all 15 unit tests passed.".xcresult bundle in Xcode, digging through attachments, and trying to visualize what the app looked like at the exact second of failure. Solution: This MCP provides specialized tools like xcresult_get_ui_hierarchy and xcresult_get_screenshot. An AI can programmatically inspect the UI state (in an AI-readable JSON format) at the specific timestamp of a failure to identify why an element wasn't tappable or visible. Example: 1. A UI test fails. The AI uses xcresult_browse to find the failure. 2. It calls xcresult_get_ui_hierarchy for the failure timestamp. 3. The AI analyzes the JSON and explains: "The 'Submit' button was actually covered by a keyboard overlay at timestamp 45.2s, which is why the test couldn't click it."xcode_get_workspace_info and xcode_get_schemes. An AI can use these to automatically understand the project structure and configure the environment correctly. Example: - User: "How do I run this project?" - AI: (Runs xcode_get_workspace_info and xcode_get_schemes) "This workspace has three schemes: MyApp, MyAppDev, and InternalTool. I recommend using MyAppDev. I also see 5 available iPhone simulators. Would you like me to build and run the…Part of MCP Servers
XcodeMCP is a Model Context Protocol server that controls Xcode on macOS using JavaScript for Automation. It allows AI assistants to build apps, run tests, manage schemes, and inspect test results inside the Xcode interface.
You can run XcodeMCP directly using npx by specifying npx -y xcodemcp@latest in your MCP client configuration, or install it globally with npm install -g xcodemcp to access the xcodecontrol CLI.
XcodeMCP works with any client supporting the Model Context Protocol over standard input and output, including Claude Desktop, Claude Code CLI, Cursor, and VS Code.
Sidekick mode runs XcodeMCP using the --sidekick-only argument. This setup disables build and run commands that Apple's native Xcode MCP handles, leaving XcodeMCP focused on project management and xcresult analysis.