📌Overview

Purpose: The Xcode MCP Server aims to facilitate the building and testing of Xcode projects through a Model Context Protocol interface, allowing AI assistants to execute these tasks seamlessly.

Overview: The Xcode MCP Server provides a standardized way for applications utilizing large language models (LLMs) to directly manage builds, run tests, and monitor activities related to Xcode projects. Its integration allows streamlined workflows for development and testing processes, enhancing productivity for developers.

Key Features:

• Project Building: Supports building Xcode projects with custom schemes and configurations, allowing flexibility in the development process.

• Granular Test Control: Enables the execution of unit tests with options to run specific tests or skip predefined ones, ensuring focused testing efforts.

• Real-time Monitoring: Streams build and test logs live, providing immediate feedback and insights into the build and testing processes.

• Detailed Reporting: Generates comprehensive build and test reports, including automatic log persistence and JSON-formatted outputs for easier consumption and analysis.

---

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, enabling 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
• 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

1. Start the server:

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

2. Configure Claude Desktop settings:

   "xcode-build": {
       "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
• 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

• 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)
• Access the latest log via the xcode-build://latest-log resource.