XcodeMCP

by lapfelix

57 234 downloads Not rated yet Apache-2.0

GitHub

About

MCP server for Xcode that wraps its AppleScript interface & uses XCLogParser to return clear build results

Details

License: Apache-2.0

Explore

XcodeMCP provides comprehensive tools for analyzing Xcode test results (.xcresult files), making it easy to debug test failures and extract valuable information:

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name XcodeMCP

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

- macOS with Xcode installed
- Node.js 18+
- XCLogParser (recommended): brew install xclogparser

XCLogParser is recommended but optional:

brew install xclogparser

Run directly with npx:

npx -y xcodemcp@latest

Or install globally:

npm install -g xcodemcp

Add to your MCP configuration:

{

  "mcpServers": {

    "xcodemcp": {

      "command": "npx",

      "args": ["-y", "xcodemcp@latest"],

      "env": {

      }

    }

  }

}

To add XcodeMCP to Claude Code using the command line:

claude mcp add-json XcodeMCP '{

  "command": "npx",

  "args": ["-y", "xcodemcp@latest"],

  "env": {

  }

}'

First, enable Xcode Tools in Xcode > Settings > Intelligence > Model Context Protocol.

Then add both Apple's Xcode MCP and XcodeMCP in sidekick mode:

json
{
"mcpServers": {
"xcode": {
"command": "xcrun",
"args": ["mcpbridge"]
},
"xcodemcp": {
"command": "npx",
"args": ["-y", "xcodemcp@latest", "--sidekick-only"]
}
}
}

> Future direction: In a future version, XcodeMCP will transition to sidekick-only mode by default, focusing exclusively on tools that complement Apple's official Xcode MCP rather than duplicating functionality.

For local development:

bash
git clone https://github.com/lapfelix/XcodeMCP.git
cd XcodeMCP
npm install

XcodeMCP includes a powerful CLI that provides 100% feature parity with the MCP server, allowing you to run any tool as a one-shot command:

bash

``bash


XcodeMCP supports configurable logging to help with debugging and monitoring:

- LOG_LEVEL: Controls logging verbosity (default: INFO) -SILENT: No logging output -ERROR: Only error messages -WARN: Warnings and errors -INFO: General operational information (recommended) -DEBUG: Detailed diagnostic information

- XCODEMCP_LOG_FILE: Optional file path for logging - Logs are written to the specified file in addition to stderr - Parent directories are created automatically - Example:/tmp/xcodemcp.log or ~/Library/Logs/xcodemcp.log

- XCODEMCP_CONSOLE_LOGGING: Enable/disable console output (default: true) - Set tofalse` to disable stderr logging (useful when using file logging only)

`xcode_open_project`

Open projects and workspaces

`xcode_get_workspace_info`

Get workspace status and details

`xcode_get_projects`

List projects in workspace

`xcode_open_file`

Open files with optional line number

`xcode_build`

Build with detailed error parsing

`xcode_clean`

Clean build artifacts

`xcode_test`

Run tests with optional arguments

`xcode_build_and_run`

Build and run the active scheme

`xcode_debug`

Start debugging session

`xcode_stop`

Stop current operation

`xcode_get_schemes`

List available schemes

`xcode_set_active_scheme`

Switch active scheme

`xcode_get_run_destinations`

List simulators and devices

`xcresult_browse`

Browse test results and analyze failures

`xcresult_browser_get_console`

Get console output for specific tests

`xcresult_summary`

Quick overview of test results

`xcresult_get_screenshot`

Extract screenshots from test failures

`xcresult_get_ui_hierarchy`

Get UI hierarchy as AI-readable JSON with timestamp selection

`xcresult_get_ui_element`

Get detailed properties of specific UI elements by index

`xcresult_list_attachments`

List all attachments for a test

`xcresult_export_attachment`

Export specific attachments from test results

`xcode_health_check`

Environment validation and troubleshooting

Project Management:
- xcode_open_project - Open projects and workspaces
- xcode_get_workspace_info - Get workspace status and details
- xcode_get_projects - List projects in workspace
- xcode_open_file - Open files with optional line number

Build Operations:
- xcode_build - Build with detailed error parsing
- xcode_clean - Clean build artifacts
- xcode_test - Run tests with optional arguments
- xcode_build_and_run - Build and run the active scheme
- xcode_debug - Start debugging session
- xcode_stop - Stop current operation

Configuration:
- xcode_get_schemes - List available schemes
- xcode_set_active_scheme - Switch active scheme
- xcode_get_run_destinations - List simulators and devices

XCResult Analysis:
- xcresult_browse - Browse test results and analyze failures
- xcresult_browser_get_console - Get console output for specific tests
- xcresult_summary - Quick overview of test results
- xcresult_get_screenshot - Extract screenshots from test failures
- xcresult_get_ui_hierarchy - Get UI hierarchy as AI-readable JSON with timestamp selection
- xcresult_get_ui_element - Get detailed properties of specific UI elements by index
- xcresult_list_attachments - List all attachments for a test
- xcresult_export_attachment - Export specific attachments from test results

Diagnostics:
- xcode_health_check - Environment validation and troubleshooting

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

Model Context Protocol (MCP) server that controls Xcode directly through JavaScript for Automation (JXA). Available as both an MCP server and a standalone CLI.

What it does

- Controls Xcode directly through JavaScript for Automation (not xcodebuild CLI)
- Opens projects, builds, runs, tests, and debugs from within Xcode
- Parses build logs with precise error locations using XCLogParser
- Provides comprehensive environment validation and health checks
- Supports graceful degradation when optional dependencies are missing
- NEW: Includes a full-featured CLI with 100% MCP server feature parity

Requirements

- macOS with Xcode installed
- Node.js 18+
- XCLogParser (recommended): brew install xclogparser

Usage

XcodeMCP can be used in two ways:
1. MCP Server: Integrate with Claude Desktop, VS Code, or other MCP clients
2. CLI Tool: Run commands directly from the terminal with xcodecontrol

Quick Install

XCLogParser is recommended but optional:

brew install xclogparser

Install from npm

Run directly with npx:

npx -y xcodemcp@latest

Or install globally:

npm install -g xcodemcp

MCP Configuration

Add to your MCP configuration:

{

  "mcpServers": {

    "xcodemcp": {

      "command": "npx",

      "args": ["-y", "xcodemcp@latest"],

      "env": {

      }

    }

  }

}

Claude Code CLI Setup

To add XcodeMCP to Claude Code using the command line:

claude mcp add-json XcodeMCP '{

  "command": "npx",

  "args": ["-y", "xcodemcp@latest"],

  "env": {

  }

}'

Without the clean build folder tool

To add XcodeMCP to Claude Code using the command line:

claude mcp add-json XcodeMCP '{

  "command": "npx",

  "args": ["-y", "xcodemcp@latest", "--no-clean"],

  "env": {

  }

}'

Using Preferred Values for Single Project Workflows

For projects where you're working with a single xcodeproj and scheme, you can configure preferred values to make tool parameters optional:

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
    "XCODE_MCP_PREFERRED_SCHEME": "MyApp",
    "XCODE_MCP_PREFERRED_XCODEPROJ": "MyApp.xcodeproj"
  }
}'

With preferred values configured:
- Tool parameters become optional instead of required
- Tool descriptions show default values (e.g., "defaults to MyApp.xcodeproj")
- You can still override defaults by providing explicit parameters
- Reduces repetition when working with a single project

Troubleshooting

If /mcp in Claude Code indicates the MCP failed, try running it from the project folder manually to see what the output is: npx -y xcodemcp@latest

Sidekick Mode

When using XcodeMCP alongside Apple's official Xcode MCP server, enable sidekick mode to only include complementary tools:

- Project management: Open/close projects, manage schemes, workspace info
- XCResult analysis: Browse test results, extract screenshots, inspect UI hierarchies

This excludes build/run/test/debug tools that Apple's MCP handles natively.

Claude Code CLI Setup (Both Servers)

First, enable Xcode Tools in Xcode > Settings > Intelligence > Model Context Protocol.

Then add both Apple's Xcode MCP and XcodeMCP in sidekick mode:
```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

xcode_open_project

xcode_get_workspace_info

xcode_get_projects

xcode_open_file

xcode_build

xcode_clean

xcode_test

xcode_build_and_run

xcode_debug

xcode_stop

xcode_get_schemes

xcode_set_active_scheme

xcode_get_run_destinations

xcresult_browse

xcresult_browser_get_console

xcresult_summary

xcresult_get_screenshot

xcresult_get_ui_hierarchy

xcresult_get_ui_element

xcresult_list_attachments

xcresult_export_attachment

xcode_health_check

Claude Desktop / Cursor

McpServers

What it does

Requirements

Usage

Quick Install

Install from npm

MCP Configuration

Claude Code CLI Setup

Without the clean build folder tool

Using Preferred Values for Single Project Workflows

Troubleshooting

Sidekick Mode

Claude Code CLI Setup (Both Servers)

Videos about XcodeMCP

Xcode 26.3: How to Enable Agentic Coding (Claude, Codex & MCP)

How XcodeBuildMCP Makes Swift Dev 10x Faster

Xcode 26.3 Is Now an MCP Server | First Look & Setup Guide

More like this

Sequential Thinking

Sentry

Github

Filesystem

`xcode_open_project`

`xcode_get_workspace_info`

`xcode_get_projects`

`xcode_open_file`

`xcode_build`

`xcode_clean`

`xcode_test`

`xcode_build_and_run`

`xcode_debug`

`xcode_stop`

`xcode_get_schemes`

`xcode_set_active_scheme`

`xcode_get_run_destinations`

`xcresult_browse`

`xcresult_browser_get_console`

`xcresult_summary`

`xcresult_get_screenshot`

`xcresult_get_ui_hierarchy`

`xcresult_get_ui_element`

`xcresult_list_attachments`

`xcresult_export_attachment`

`xcode_health_check`