Xcode MCP server

MCP Xcode Server is a specialized tool that enables AI assistants to build, test, run, and manage Apple platform projects through natural language interactions. It bridges the gap between AI tools and Apple's development ecosystem, allowing automated workflows without manual intervention while maintaining token efficiency.

Installation Requirements

Prerequisites

• macOS 14.0 or later
• Xcode 16.0 or later
• Node.js 18+
• Xcode Command Line Tools
• Simulators for target platforms

Setup Process

The quickest way to get started is by using npm:

# Install globally
npm install -g mcp-xcode-server

# Run interactive setup
mcp-xcode-server setup

The setup wizard handles:

• Configuring the MCP server for Claude
• Setting up Xcode sync hooks (optional)
• Building necessary helper tools

Manual Configuration

If you prefer manual setup, add the following to ~/.claude.json (for global settings) or .claude/settings.json (for project-specific settings):

{
  "mcpServers": {
    "mcp-xcode-server": {
      "type": "stdio",
      "command": "mcp-xcode-server",
      "args": ["serve"],
      "env": {}
    }
  }
}

Available Tools

Building Applications

• build_xcode: Build Xcode projects/workspaces with support for custom configurations
• build_swift_package: Build Swift packages (limited to Debug/Release configurations)
• run_xcode: Build and run applications on simulators or macOS
• run_swift_package: Execute Swift package executables

Testing

• test_xcode: Run XCTest or Swift Testing suites
• test_swift_package: Test Swift packages
• Both testing tools support filtering by class or method

Project Information

• list_schemes: Display available Xcode schemes
• get_project_info: Retrieve comprehensive project details
• list_targets: See all build targets
• get_build_settings: Access scheme configuration details

Simulator Management

• list_simulators: Display available simulator devices
• boot_simulator: Start a specific simulator
• shutdown_simulator: Stop a simulator
• view_simulator_screen: Capture a screenshot of the simulator

App Management

• install_app: Install an application on a simulator
• uninstall_app: Remove an app using its bundle ID
• get_device_logs: Retrieve and filter device logs

Distribution

• archive_project: Create an .xcarchive file
• export_ipa: Export an IPA file from an archive

Maintenance

• clean_build: Clean build artifacts and DerivedData
• manage_dependencies: Add, remove, or update Swift packages

Platform Support

The server supports multiple Apple platforms with the following requirements:

Platform	Simulator Required	Default Device	Min Version
iOS	Yes	iPhone 16 Pro	iOS 17+
macOS	No	Host machine	macOS 14+
tvOS	Yes	Apple TV	tvOS 17+
watchOS	Yes	Apple Watch Series 10	watchOS 10+
visionOS	Yes	Apple Vision Pro	visionOS 1.0+

Limitations

Current Constraints

• No SwiftUI Previews support (requires full Xcode IDE)
• Cannot perform interactive UI testing (taps, swipes, etc.)
• Works with simulators only, not physical devices
• No debugging capabilities (breakpoints, LLDB access)
• No access to Xcode UI features like storyboard editing
• Platform requirements: macOS 14+, Xcode 16+, iOS 17+ simulators

When to Use Xcode Instead

You'll still need Xcode for:

• Designing UI with Interface Builder or SwiftUI previews
• Debugging with breakpoints and variable inspection
• Profiling with Instruments
• Managing certificates and provisioning profiles
• Testing on physical devices
• Using Xcode-specific features (Playgrounds, AR tools, etc.)

Logging

All operations are automatically logged to ~/.mcp-xcode-server/logs/:

• Organized in daily folders (e.g., 2025-01-27/)
• 7-day automatic retention
• Complete xcodebuild/swift output preserved
• Symlinks to latest logs for easy access

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-xcode-server" '{"type":"stdio","command":"mcp-xcode-server","args":["serve"],"env":[]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-xcode-server": {
            "type": "stdio",
            "command": "mcp-xcode-server",
            "args": [
                "serve"
            ],
            "env": []
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-xcode-server": {
            "type": "stdio",
            "command": "mcp-xcode-server",
            "args": [
                "serve"
            ],
            "env": []
        }
    }
}

3. Restart Claude Desktop for the changes to take effect