analyze_file
Analyzes a source file for potential issues using Xcode's static analyzer.
LABSCO SUMMARY
The edit-build-test-simulator loop happens in one place instead of four.
Because build_project, run_tests and the simulator tools all run against the same active project, a failing test can be read, patched and re-run without anyone switching windows, and run_xcrun keeps the rest of the toolchain one call away. Two things to check before you plan around it: the docs describe a wider catalogue — CocoaPods, directory stacks, archiving, screenshots — than the tool list a client is actually handed, and PROJECTS_BASE_DIR is the security boundary, so anything outside it has to be named in ALLOWED_PATHS before a read or write will succeed.
What it is
A local bridge to Xcode's own command-line tooling. One project is active at a time; file access is confined to the projects base directory plus any extra paths you allow, and builds, tests and simulator control run through xcodebuild and xcrun.
What you get
- An active project set by .xcodeproj path, with its details read back and its files listed by type
- Source read and written inside the project, with write_file creating the file when createIfMissing is set
- build_project against a named scheme and configuration, and run_tests with an optional test plan
- analyze_file runs Xcode's static analyzer over a single source file
- list_simulators returns what xcrun simctl list --json reports, and boot_simulator and shutdown_simulator drive one by UDID
- run_xcrun passes a tool name and arguments through to xcrun, which is the escape hatch when no dedicated tool exists
- run_lldb launches the debugger with your own arguments, and trace_app captures an xctrace performance trace of an app bundle for a duration you set
- compile_asset_catalog runs actool over a catalog into an output directory
- swift_package_update runs swift package update for Swift Package Manager dependencies
Requirements
macOS with Xcode 14.0 or higher and the Command Line Tools, plus Node.js 16 or higher; Swift 5.5+ for the Swift Package Manager tools and CocoaPods only if you use the pod commands. No account or key. PROJECTS_BASE_DIR sets which directories the file tools may touch; without it the server falls back to the first of ~/Documents, ~/Projects or ~/Developer that exists. ALLOWED_PATHS adds more, comma-separated, and both have command-line equivalents (--projects-dir, --allowed-paths). PORT defaults to 3000; DEBUG and LOG_LEVEL control logging. Published as xcode-mcp-server with the binary xcode-server.
Setup effort
Build from source — git clone https://github.com/r-huijts/xcode-mcp-server.git
USE CASES
01
Fixing a failing test without leaving the conversation
Run the tests, read the source file the failure points at, write the fix, and build again — all against the one active project.
02
Getting a build onto a simulator to look at it
Build the scheme, see which simulators exist and what state they are in, and boot the one you want.
03
Working out why a source file misbehaves before it ships
Run Xcode's static analyzer over the file, read what it flags, and rewrite the part it objects to.
04
Chasing a performance problem in a built app
Capture an xctrace trace of the app bundle for a set duration, and attach the debugger when the trace points at something you need to step through.
05
Reaching an Xcode tool that has no dedicated call
Name the xcrun tool and its arguments yourself — the same escape hatch that covers asset catalogue compilation and package updates when the dedicated tools stop short.
18 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
boot_simulator
Boots an iOS simulator identified by its UDID.
build_project
Builds the active Xcode project using the specified configuration and scheme.
compile_asset_catalog
Compiles an asset catalog using 'actool'.
get_active_project
Retrieves detailed information about the currently active Xcode project.
list_directory
Lists the contents of a directory, showing both files and subdirectories.
list_project_files
Lists all files within an Xcode project.
list_simulators
Lists all available iOS simulators with their details by invoking 'xcrun simctl list --json'.
read_file
Reads the contents of a file within the active Xcode project.
run_lldb
Launches the LLDB debugger with custom arguments.
run_tests
Executes tests for the active Xcode project.
run_xcrun
Executes a specified Xcode tool via 'xcrun'.
set_project_path
Sets the active Xcode project by specifying the path to its .xcodeproj directory.
set_projects_base_dir
Sets the base directory where your Xcode projects are stored.
shutdown_simulator
Shuts down an active iOS simulator using its UDID.
swift_package_update
Updates the dependencies of your Swift project using Swift Package Manager by invoking 'swift package update'.
trace_app
Captures a performance trace of an application using 'xctrace'.
write_file
Writes or updates the content of a file in the active Xcode project.
BEFORE YOU INSTALL
What to know first
Tools you get
18 tools when we connected; the project documents 60. The project does not say which tools need a setting to appear; optional CocoaPods and Swift 5.5+ for SPM may gate some. Live names differ from the docs: swift_package_update, not update_swift_package, and run_tests, not test_project.
Requires
- macOS with Xcode 14.0 or higher and the Xcode Command Line Tools
- Node.js 16 or higher
- npm or yarn
- Swift 5.5+ for Swift Package Manager features
- CocoaPods (optional, for CocoaPods integration)
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server
npm install
npm run build
cp .env.example .envEdit .env and set PROJECTS_BASE_DIR=<YOUR_PROJECTS_BASE_DIR> — the directory the file tools may read and write; ALLOWED_PATHS adds more directories, comma-separated.
MCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"xcode": {
"command": "node",
"args": [
"<YOUR_PATH_TO_XCODE_MCP_SERVER>/dist/index.js"
],
"env": {
"PROJECTS_BASE_DIR": "<YOUR_PROJECTS_BASE_DIR>"
}
}
}
}Put this in ~/Library/Application Support/Claude/claude_desktop_config.json. <YOUR_PATH_TO_XCODE_MCP_SERVER> is the full path of your clone, and <YOUR_PROJECTS_BASE_DIR> is the directory that holds your Xcode projects. The server reads .env from the directory it is started in, and Claude Desktop does not start it in the clone, so the base directory is set in env here; without it the server falls back to the first of ~/Documents, ~/Projects or ~/Developer that exists.
