XcodeMCP

XcodeMCP is a Model Context Protocol (MCP) server that lets you control Xcode directly from JavaScript for Automation (JXA). It enables opening projects, building, running, testing, and debugging from within Xcode, while providing precise error parsing and health checks. It also ships with a full-featured CLI so you can perform MCP-enabled actions from the terminal. This makes it easy to automate Xcode workflows from MCP clients like Claude Desktop or VS Code, or to run one-shot commands from your terminal.

How to use

You operate XcodeMCP through an MCP client or the built-in CLI. When using a client, you send requests to the MCP server and perform actions such as opening a project, building a scheme, running tests, debugging sessions, or analyzing test results. The server exposes a rich set of tools to manage Xcode workflows and parse build outputs, including log parsing with precise error locations.

How to install

Prerequisites: you need macOS with Xcode installed and Node.js 18+ on your system. If you want advanced build log analysis, install XCLogParser (recommended). You can install XCLogParser with Homebrew.

Additional setup and usage notes

This section covers configuration, health checks, CLI usage, and troubleshooting to help you get up and running quickly.

Configuration

Configure XcodeMCP to run as a local MCP server using the MCP configuration block below. This uses npx to run the latest XcodeMCP package and keeps the command line invocation simple for local development and integration with MCP clients.

Troubleshooting

If an issue occurs, start by validating the environment and ensuring XCLogParser is available if you rely on build log parsing. Run a health check to gather diagnostics and confirm that Xcode is detected and functional.

Examples

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
      }
    }
  }
}

Claude Code CLI setup and workflow

You can add XcodeMCP to Claude Code using a single JSON snippet that points to the MCP server configuration. This enables Claude Code to relay MCP tool invocations to XcodeMCP for execution.

Developer setup

If you want to contribute or run XcodeMCP locally, clone the project, install dependencies, and run in development or build mode. The development workflow uses TypeScript. Build and start the compiled server for production-like runs.

Available tools

xcode_open_project

Open projects and workspaces inside Xcode via MCP commands.

xcode_get_workspace_info

Retrieve workspace status and details to understand current project state.

xcode_get_projects

List available projects within a workspace to help navigate large repos.

xcode_open_file

Open a specific file in Xcode with an optional line number for quick navigation.

xcode_build

Build a project or scheme with detailed error parsing for quick debugging.

xcode_clean

Clean build artifacts to ensure a fresh build environment.

xcode_test

Run tests for a project or scheme with configurable arguments.

xcode_build_and_run

Build the active scheme and launch the application for quick iteration.

xcode_debug

Start a debugging session for the active target.

xcode_stop

Stop the current operation or process running in Xcode via MCP.

xcode_get_schemes

List available schemes for a given project to choose build targets.

xcode_set_active_scheme

Switch the active scheme for subsequent builds/runs.

xcode_get_run_destinations

List simulators and devices available for running the app.

xcresult_browse

Browse XCResult test result files to inspect outcomes.

xcresult_browser_get_console

Extract console output for specific tests from XCResult.

xcresult_summary

Provide a quick summary of test results and outcomes.

xcresult_get_screenshot

Extract screenshots from test failures in XCResult.

xcresult_get_ui_hierarchy

Get UI hierarchy as AI-readable JSON with optional timestamp.

xcresult_get_ui_element

Inspect specific UI elements in a UI hierarchy by index.

xcresult_list_attachments

List all attachments for a given test in XCResult.

xcresult_export_attachment

Export specific attachments from XCResult by type or index.

xcode_health_check

Environment validation and troubleshooting to ensure MCP can operate smoothly.