MCP Xcode Server

An MCP (Model Context Protocol) server that provides tools for interacting with Xcode projects programmatically.

Installation

Clone this repository:

git clone https://github.com/chacebot/mcp-xcode-server.git
cd mcp-xcode-server
npm install

Or install from a local directory:

cd /path/to/mcp-xcode-server
npm install

Features

This server provides the following tools for Xcode project management:

• xcode_read_project - Read and parse Xcode project files

• xcode_list_schemes - List all build schemes in a project

• xcode_list_targets - List all targets in a project

• xcode_add_test_target - Add a test target to a project

• xcode_configure_test_target - Configure a test target for a project

• xcode_add_file_to_target - Add files to project targets

• xcode_remove_file_from_target - Remove files from project targets

• xcode_list_files_in_target - List all files in a target

• xcode_build - Build Xcode projects

• xcode_test - Run tests in Xcode projects

• xcode_get_build_settings - Get build settings

• xcode_get_build_errors - Get and parse build errors

• xcode_clean - Clean build artifacts

• xcode_validate_project - Validate project structure and check for issues

Quick Start

1. Install dependencies:

   npm install

2. Configure your MCP client (Claude Desktop, Cursor, etc.):

   {
     "mcpServers": {
       "xcode": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-xcode-server/src/index.js"],
         "env": {}
       }
     }
   }

3. Restart your MCP client to load the server

4. Start using Xcode tools through your AI assistant!

See QUICKSTART.md for a 5-minute setup guide, or SETUP.md for detailed instructions.

Usage

As an MCP Server

Configure this server in your MCP client configuration. For example, in Claude Desktop or Cursor:

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/path/to/mcp-xcode-server/src/index.js"],
      "env": {}
    }
  }
}

Standalone Testing

You can test the server directly:

npm start

The server communicates via stdio using the MCP protocol.

Requirements

• Node.js 18+

• Xcode command-line tools installed

• Access to Xcode projects

Tools Reference

xcode_read_project

Read and parse an Xcode project file to extract its structure.

Parameters:

• projectPath (required): Path to the .xcodeproj file

Example:

{
  "name": "xcode_read_project",
  "arguments": {
    "projectPath": "/path/to/Project.xcodeproj"
  }
}

xcode_list_schemes

List all build schemes available in the project.

Parameters:

• projectPath (required): Path to the .xcodeproj file

xcode_list_targets

List all targets in the project.

Parameters:

• projectPath (required): Path to the .xcodeproj file

xcode_add_test_target

Add a new test target to the project. Note: This currently provides instructions rather than directly modifying the pbxproj file, as that requires careful parsing and manipulation.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• targetName (optional): Name for the test target (defaults to ProjectNameTests)

xcode_add_file_to_target

Add a file to a specific target in the project.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• filePath (required): Relative path to the file from project root

• targetName (required): Name of the target

xcode_build

Build the Xcode project using xcodebuild.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• scheme (optional): Build scheme name

• configuration (optional): Debug or Release (default: Debug)

xcode_test

Run tests in the Xcode project.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• scheme (optional): Test scheme name

xcode_get_build_settings

Get build settings for the project or a specific scheme.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• scheme (optional): Scheme name

• configuration (optional): Debug or Release (default: Debug)

xcode_clean

Clean build artifacts from the project.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• scheme (optional): Build scheme name

xcode_remove_file_from_target

Remove a file from an Xcode project target.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• filePath (required): Relative path to the file from project root

• targetName (required): Name of the target

xcode_get_build_errors

Get build errors from the last build attempt. Parses xcodebuild output to extract error messages.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• scheme (optional): Build scheme name

xcode_list_files_in_target

List all files in a specific target.

Parameters:

• projectPath (required): Path to the .xcodeproj file

• targetName (required): Name of the target

xcode_validate_project

Validate Xcode project structure and check for common issues like missing targets, schemes, or configuration problems.

Parameters:

• projectPath (required): Path to the .xcodeproj file

Limitations

• The pbxproj parser is simplified and may not handle all edge cases

• Adding targets/files requires careful manipulation of the pbxproj format

• Some operations may require Xcode to be installed and properly configured

Future Improvements

• Full pbxproj parser using a proper library (e.g., xcode npm package)

• Better error handling and validation

• Support for Xcode workspaces (.xcworkspace)

• Support for Swift Package Manager integration

• Support for modifying build settings

• Support for managing code signing

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/my-feature

3. Commit your changes: git commit -am 'Add some feature'

4. Push to the branch: git push origin feature/my-feature

5. Submit a pull request

License

MIT - see LICENSE file for details