Xcode MCP Server

Use This MCP server To

Trigger Xcode project builds from AI assistants Run specific unit tests or skip tests programmatically Stream real-time build and test logs to AI clients Generate and retrieve code coverage reports Access detailed build and test reports via JSON Automate continuous integration workflows for iOS/macOS Persist build and test logs automatically for auditing

README

Xcode MCP Server

A Model Context Protocol server for building Xcode projects directly from LLM applications

The Xcode MCP Server provides a Model Context Protocol interface for building and testing Xcode projects. It enables AI assistants to directly trigger builds, run tests, monitor progress, and access logs through a standardized interface.

Features

Build Xcode projects with custom schemes and configurations
Run unit tests with granular control (run specific tests or skip tests)
Generate code coverage reports
Stream build and test logs in real-time
Access detailed build and test reports
JSON-formatted output
Automatic log persistence

Requirements

Node.js 16+
Xcode Command Line Tools
TypeScript
MCP-compatible client (e.g., Claude Desktop)

Installation

# Clone the repository
git clone https://github.com/PolarVista/Xcode-mcp-server.git
cd xcode-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

Usage with Claude Desktop

Start the server:

npm run start /path/to/build/logs/directory

In Claude Desktop settings:

       "command": "node",
       "args": ["/path/to/the/xcode-mcp-server/build/index.js",
                "/path/to/your/project/folder"],
       "env": {
         "PATH": "/usr/bin:/bin:/usr/local/bin:/usr/sbin:/sbin"
   }

Available Tools

build_project

Builds an Xcode project with specified parameters.

Parameters:

projectPath (required): Path to the .xcodeproj or .xcworkspace
scheme (required): Build scheme name
configuration (optional): Build configuration (Debug/Release, defaults to Debug)
destination (optional): Build destination (defaults to "platform=iOS Simulator,name=iPhone 15 Pro")

Example usage in Claude:

build_project({
  projectPath: "/path/to/Project.xcodeproj",
  scheme: "MyApp",
  configuration: "Debug"
})

run_tests

Runs unit tests with optional filtering.

Parameters:

projectPath (required): Path to the .xcodeproj or .xcworkspace
scheme (required): Test scheme name
testIdentifier (optional): Specific test to run (e.g., 'MyTests/testExample')
skipTests (optional): Array of test identifiers to skip
configuration (optional): Build configuration (Debug/Release, defaults to Debug)
destination (optional): Test destination (defaults to "platform=iOS Simulator,name=iPhone 15 Pro")

Example usage in Claude:

run_tests({
  projectPath: "/path/to/Project.xcodeproj",
  scheme: "MyAppTests",
  testIdentifier: "LoginTests/testSuccessfulLogin",
  skipTests: ["PerformanceTests/testLargeDataLoad"],
  configuration: "Debug"
})

Logs

All logs are stored in the specified base directory under build-logs/
Build operations create:
- Plain text log (build-[timestamp].log)
- JSON-formatted log (build-[timestamp].log.json)
- Xcode report (report-[timestamp].txt)
Test operations create:
- Test log (test-[timestamp].log)
- JSON-formatted log (test-[timestamp].log.json)
- Test report (test-report-[timestamp].txt)
- Code coverage report (coverage-[timestamp].txt)
Latest log (build or test) is accessible via the xcode-build://latest-log resource

Xcode-mcp-server FAQ

How do I install the Xcode MCP Server?

Clone the GitHub repository, install dependencies with npm, and ensure Node.js 16+, Xcode Command Line Tools, and TypeScript are installed.

Can the Xcode MCP Server run specific tests only?

Yes, it supports granular control to run or skip specific unit tests within your Xcode projects.

How does the server provide build and test feedback?

It streams build and test logs in real-time and outputs detailed reports in JSON format for easy consumption by AI clients.

Is log data persisted automatically?

Yes, the server automatically persists build and test logs for later review or auditing purposes.

What MCP clients are compatible with the Xcode MCP Server?

It works with any MCP-compatible client, such as Claude Desktop, enabling seamless AI integration.

What are the system requirements for running the Xcode MCP Server?

Requires Node.js 16 or higher, Xcode Command Line Tools installed on macOS, and TypeScript.

Can this server be used to automate CI/CD pipelines?

Yes, it can be integrated into AI-driven continuous integration workflows for building and testing iOS/macOS projects.

Does the server support custom build schemes and configurations?

Yes, you can specify custom schemes and configurations when triggering builds through the MCP interface.