MCP Xcode Server

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

Installation

Clone this repository:

Or install from a local directory:

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:

Standalone Testing

You can test the server directly:

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:

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