Polarvista Xcode MCP Server

🚀 Xcode MCP Server

A Model Context Protocol server for building and testing Xcode projects directly from large language model 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 standardized way for AI assistants to interact with Xcode projects. It allows you to perform various operations such as building projects, running tests, and accessing logs.

✨ Features

• Build Xcode projects using 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.
• 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

Step 1: Start the server

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

Step 2: Configure in Claude Desktop

"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): Identifier for a specific test (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 stored in the build-logs/ folder under the specified base directory.
• Build operations create:
  • Plain text logs (build-[timestamp].log).
  • JSON format logs (build-[timestamp].log.json).
  • Xcode reports (build-[timestamp].xcresult).
• Test operations create:
  • Plain text logs (test-[timestamp].log).
  • JSON format logs (test-[timestamp].log.json).
  • Xcode reports (test-[timestamp].xcresult).

You can access the latest build and test results via the following URL:

http://localhost:8080