Xcode MCP Server

🚀 Xcode MCP Server

A Model Context Protocol server created 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.

🚀 Quick Start

The Xcode MCP Server offers a Model Context Protocol interface for building and testing Xcode projects, allowing AI assistants to trigger builds, run tests, monitor progress, and access logs via a standardized interface.

✨ Features

• Build Xcode projects using custom schemes and configurations.
• Run unit tests with fine-grained control (run specific tests or skip certain tests).
• Generate code coverage reports.
• Stream build and test logs in real-time.
• Access detailed build and test reports.
• Output in JSON format.
• Automatically persist logs.

📦 Installation

Prerequisites

• Node.js version 16 or higher.
• Xcode Command Line Tools.
• TypeScript.
• An MCP-compatible client (e.g., Claude Desktop).

Steps

# 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 Examples

Using with Claude Desktop

1. Start the server:

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

2. In the 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

Build an Xcode project with specified parameters.

Parameters:

• projectPath (required): Path to the .xcodeproj or .xcworkspace file.
• scheme (required): Name of the build scheme.
• configuration (optional): Build configuration (Debug/Release, default is Debug).
• destination (optional): Build destination (default is "platform=iOS Simulator,name=iPhone 15 Pro").

Example usage in Claude:

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

run_tests

Run unit tests with optional filtering.

Parameters:

• projectPath (required): Path to the .xcodeproj or .xcworkspace file.
• scheme (required): Name of the test scheme.
• testIdentifier (optional): ID of a specific test case (e.g., 'MyTests/testExample').
• skipTests (optional): Array of test identifiers to skip.
• configuration (optional): Build configuration (Debug/Release, default is Debug).
• destination (optional): Test destination (default is "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"
})

📚 Documentation

Logs

• All logs are saved in the build-logs/ directory under the specified base directory.
• Build operations generate:
  • Text logs (build-[timestamp].log).
  • JSON-formatted logs (build-[timestamp].log.json).
  • Xcode reports (report-[timestamp].txt).
• Test operations generate:
  • Test logs (test-[timestamp].log).
  • JSON-formatted logs (test-[timestamp].log.json).
  • Test reports (test-report-[timestamp].txt).
  • Code coverage reports (coverage-[timestamp].txt).
• The latest logs (build or test) can be accessed via xcode-build/[timestamp]/latest.