Xcode MCP Server

A Model Context Protocol (MCP) server for Xcode project management. Provides 16 tools for building, testing, running, and managing Xcode projects and simulators — all from your AI agent or terminal.

Why This Exists

Apple ships an official mcpbridge binary with Xcode 26.3+ that provides MCP integration. However, it is broken on macOS 15.x (Sequoia) due to a missing Swift symbol (_$s10AppSandbox17ASBBinaryIdentityC14teamIdentifierSSSgvg) in the AppSandbox private framework. The binary was compiled against macOS 16+ SDK symbols and crashes immediately on macOS 15.7.3:

dyld: Symbol not found: _$s10AppSandbox17ASBBinaryIdentityC14teamIdentifierSSSgvg
  Referenced from: /Applications/Xcode.app/Contents/Developer/usr/bin/mcpbridge
  Expected in: /System/Library/PrivateFrameworks/AppSandbox.framework/Versions/A/AppSandbox

This server is a drop-in replacement that wraps xcodebuild, xcrun, and standard file operations to provide the same capabilities — compatible with macOS 15.x and Xcode 26.3.

Tools

Tool	Description
xcode_status	Xcode version, SDK paths, available platforms
xcode_list_projects	Find .xcodeproj and .xcworkspace files
xcode_list_schemes	List all schemes in a project/workspace
xcode_list_targets	List all build targets
xcode_build	Build a project (auto-detects scheme, configurable SDK/destination)
xcode_test	Run tests (with optional test target filter)
xcode_clean	Clean build folder
xcode_run	Build + install + launch in simulator
xcode_list_simulators	List available iOS/tvOS/watchOS/visionOS simulators
xcode_boot_simulator	Boot a simulator by name or UDID
xcode_read_file	Read a source file
xcode_write_file	Write content to a file
xcode_grep	Regex search across project files
xcode_list_files	List files with glob filtering
xcode_project_info	Project metadata (schemes, targets, build settings)

Requirements

• macOS 15.x or later
• Xcode 26.3+ (works with the built-in xcodebuild and xcrun)
• Python 3.10+ (no external dependencies — stdlib only)

Installation

1. Clone

git clone git@github.com:MrAlob/xcode-mcp-server.git

2. Configure Hermes Agent

Add to ~/.hermes/config.yaml under mcp_servers:

mcp_servers:
  xcode:
    command: "python3"
    args: ["/path/to/xcode-mcp-server/xcode_mcp_server.py"]
    timeout: 300
    connect_timeout: 30

3. Restart Hermes

launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway-sol.plist
launchctl load ~/Library/LaunchAgents/ai.hermes.gateway-sol.plist

The tools will be available as mcp_xcode_* in your agent.

Usage Examples

Once connected through Hermes Agent:

• "Build the iOS project in the current directory" → calls xcode_build with auto-detected scheme
• "Run the tests for MyApp" → calls xcode_test with only_testing: MyAppTests
• "List available simulators" → calls xcode_list_simulators
• "Build and run on iPhone 16 simulator" → calls xcode_run with device: iPhone 16
• "Search for TODO across all Swift files" → calls xcode_grep with pattern: TODO, file_glob: *.swift

Protocol

Uses the MCP stdio transport (JSON-RPC 2.0 over stdin/stdout). Compatible with any MCP client, not just Hermes Agent.

License

MIT