The Xcode MCP Server exposes a suite of tools to AI assistants via the Model Context Protocol. It can manage Xcode projects, manipulate project files, integrate with CocoaPods and Swift Package Manager, run builds and tests, and interact with iOS simulators. By starting the Node.js server, clients can request project creation, add files to targets, parse workspaces, list schemes, read and write files (including binary data), and execute various Xcode and system tasks through a consistent MCP API. To connect, run the server locally (for example on http://localhost:3000) and configure your AI assistant to target that URL; the assistant will then be able to invoke the provided MCP endpoints for Xcode-related operations.

Prerequisites:

• macOS with Xcode 14.0 or higher installed
• Node.js 16 or higher
• npm or yarn
• Ruby (for CocoaPods support, optional)
• CocoaPods (optional)

Installation steps (manual):

1. Clone the repository and install dependencies: git clone https://github.com/r-huijts/xcode-mcp-server.git cd xcode-mcp-server npm install

2. Build the project: npm run build

3. Create a configuration file (example using .env): cp .env.example .env

   or create minimal config

   echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env echo "DEBUG=false" >> .env

4. Start the server: npm start

Optional Claude Desktop integration:

• Update Claude Desktop config to point to the built index.js, for example: { "mcpServers": { "xcode": { "command": "node", "args": ["/path/to/xcode-mcp-server/dist/index.js"] } } }

Troubleshooting quick checks:

• Ensure Node.js v16+ is active and run npm install again if needed
• If build errors occur, check TypeScript compile issues with npx tsc --noEmit
• Verify PROJECTS_BASE_DIR points to a real directory
• For Claude Desktop, ensure the path to index.js is correct and restart Claude after changes

Tips and common considerations:

• The server exposes MCP endpoints compatible with AI assistants; ensure your client is configured to communicate using MCP payloads.
• Environment variables control base project directory, access permissions, port, and debug logging. Keep PROJECTS_BASE_DIR secure and writable by the service.
• If using CocoaPods or Swift Package Manager features, ensure Xcode tooling and Ruby/Gems are available as needed.
• When integrating with Claude Desktop or other CLIs, provide the correct path to the compiled dist/index.js file.
• If you encounter permission issues on macOS, verify that the user running the server has access to the projects directory and any required tools.