Xcode MCP Server

1[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/r-huijts-xcode-mcp-server-badge.png)](https://mseep.ai/app/r-huijts-xcode-mcp-server)
2 
3# Xcode MCP Server
4 
5An MCP (Model Context Protocol) server providing comprehensive Xcode integration for AI assistants. This server enables AI agents to interact with Xcode projects, manage iOS simulators, and perform various Xcode-related tasks with enhanced error handling and support for multiple project types.
6 
7## Features
8 
9### Project Management
10- Set active projects and get detailed project information
11- Create new Xcode projects from templates (iOS, macOS, watchOS, tvOS)
12- Add files to Xcode projects with target and group specification
13- Parse workspace documents to find associated projects
14- List available schemes in projects and workspaces
15 
16### File Operations
17- Read/write files with support for different encodings
18- Handle binary files with base64 encoding/decoding
19- Search for text content within files using patterns and regex
20- Check file existence and get file metadata
21- Create directory structures automatically
22 
23### Build & Testing
24- Build projects with customizable options
25- Run tests with detailed failure reporting
26- Analyze code for potential issues
27- Clean build directories
28- Archive projects for distribution
29 
30### CocoaPods Integration
31- Initialize CocoaPods in projects
32- Install and update pods
33- Add and remove pod dependencies
34- Execute arbitrary pod commands
35 
36### Swift Package Manager
37- Initialize new Swift packages
38- Add and remove package dependencies with various version requirements
39- Update packages and resolve dependencies
40- Generate documentation for Swift packages using DocC
41- Run tests and build Swift packages
42 
43### iOS Simulator Tools
44- List available simulators with detailed information
45- Boot and shut down simulators
46- Install and launch apps on simulators
47- Take screenshots and record videos
48- Manage simulator settings and state
49 
50### Xcode Utilities
51- Execute Xcode commands via xcrun
52- Compile asset catalogs
53- Generate app icon sets from source images
54- Trace app performance
55- Export and validate archives for App Store submission
56- Switch between different Xcode versions
57 
58## Installation
59 
60### Prerequisites
61 
62- macOS with Xcode 14.0 or higher installed
63- Node.js 16 or higher
64- npm or yarn
65- Swift 5.5+ for Swift Package Manager features
66- CocoaPods (optional, for CocoaPods integration)
67 
68### Setup
69 
70#### Option 1: Automated Setup (Recommended)
71 
72Use the included setup script which automates the installation and configuration process:
73 
74```bash
75# Make the script executable
76chmod +x setup.sh
77 
78# Run the setup script
79./setup.sh
80```
81 
82**What the Setup Script Does:**
83 
841. **Environment Verification**:
85   - Checks that you're running on macOS
86   - Verifies Xcode is installed and accessible
87   - Confirms Node.js (v16+) and npm are available
88   - Checks for Ruby installation
89   - Verifies CocoaPods installation (offers to install if missing)
90 
912. **Dependency Installation**:
92   - Runs `npm install` to install all required Node.js packages
93   - Executes `npm run build` to compile the TypeScript code
94 
953. **Configuration Setup**:
96   - Creates a `.env` file if one doesn't exist
97   - Prompts for your projects base directory
98   - Asks if you want to enable debug logging
99   - Saves your configuration preferences
100 
1014. **Claude Desktop Integration** (Optional):
102   - Offers to configure the server for Claude Desktop
103   - Creates or updates the Claude Desktop configuration file
104   - Sets up the proper command and arguments to launch the server
105 
106**When to Use the Setup Script:**
107 
108- First-time installation to ensure all prerequisites are met
109- When you want guided configuration with interactive prompts
110- If you want to quickly set up Claude Desktop integration
111- To verify your environment has all necessary components
112 
113The script will guide you through the configuration process with clear prompts and helpful feedback.
114 
115#### Option 2: Manual Setup
116 
117**When to Use Manual Setup:**
118 
119- You prefer explicit control over each installation step
120- You have a custom environment or non-standard configuration
121- You're setting up in a CI/CD pipeline or automated environment
122- You want to customize specific aspects of the installation process
123- You're an experienced developer familiar with Node.js projects
124 
125Follow these steps for manual installation:
126 
1271. Clone the repository:
128   ```bash
129   git clone https://github.com/r-huijts/xcode-mcp-server.git
130   cd xcode-mcp-server
131   ```
132 
1332. Verify prerequisites (these must be installed):
134   - Xcode and Xcode Command Line Tools
135   - Node.js v16 or higher
136   - npm
137   - Ruby (for CocoaPods support)
138   - CocoaPods (optional, for pod-related features)
139 
1403. Install dependencies:
141   ```bash
142   npm install
143   ```
144 
1454. Build the project:
146   ```bash
147   npm run build
148   ```
149 
1505. Create a configuration file:
151   ```bash
152   # Option A: Start with the example configuration
153   cp .env.example .env
154 
155   # Option B: Create a minimal configuration
156   echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
157   echo "DEBUG=false" >> .env
158   ```
159 
160   Edit the `.env` file to set your preferred configuration.
161 
1626. For Claude Desktop integration (optional):
163   - Edit or create `~/Library/Application Support/Claude/claude_desktop_config.json`
164   - Add the following configuration (adjust paths as needed):
165   ```json
166   {
167     "mcpServers": {
168       "xcode": {
169         "command": "node",
170         "args": ["/path/to/xcode-mcp-server/dist/index.js"]
171       }
172     }
173   }
174   ```
175 
176### Setup Troubleshooting
177 
178**Common Setup Issues:**
179 
1801. **Build Errors**:
181   - Ensure you have the correct Node.js version (v16+)
182   - Try deleting `node_modules` and running `npm install` again
183   - Check for TypeScript errors with `npx tsc --noEmit`
184   - Make sure all imports in the code are properly resolved
185 
1862. **Missing Dependencies**:
187   - If you see errors about missing modules, run `npm install` again
188   - For native dependencies, you may need Xcode Command Line Tools: `xcode-select --install`
189 
1903. **Permission Issues**:
191   - Ensure you have write permissions to the installation directory
192   - For CocoaPods installation, you may need to use `sudo gem install cocoapods`
193 
1944. **Configuration Problems**:
195   - Verify your `.env` file has the correct format and valid paths
196   - Make sure `PROJECTS_BASE_DIR` points to an existing directory
197   - Check that the path doesn't contain special characters that need escaping
198 
1995. **Claude Desktop Integration**:
200   - Ensure the path in the Claude configuration points to the correct location of `index.js`
201   - Restart Claude Desktop after making configuration changes
202   - Check that the server is running before attempting to use it with Claude
203 
204## Usage
205 
206### Starting the Server
207 
208```bash
209npm start
210```
211 
212For development mode with automatic restarts:
213```bash
214npm run dev
215```
216 
217### Configuration Options
218 
219You can configure the server in two ways:
220 
2211. Environment variables in `.env` file:
222   ```
223   PROJECTS_BASE_DIR=/path/to/your/projects
224   DEBUG=true
225   ALLOWED_PATHS=/path/to/additional/allowed/directory
226   PORT=8080
227   ```
228 
2292. Command line arguments:
230   ```bash
231   npm start -- --projects-dir=/path/to/your/projects --port=8080
232   ```
233 
234### Key Configuration Parameters
235 
236- `PROJECTS_BASE_DIR` / `--projects-dir`: Base directory for projects (required)
237- `ALLOWED_PATHS` / `--allowed-paths`: Additional directories to allow access to (comma-separated)
238- `PORT` / `--port`: Port to run the server on (default: 3000)
239- `DEBUG` / `--debug`: Enable debug logging (default: false)
240- `LOG_LEVEL` / `--log-level`: Set logging level (default: info)
241 
242### Connecting to AI Assistants
243 
244The server implements the Model Context Protocol (MCP), making it compatible with various AI assistants that support this protocol. To connect:
245 
2461. Start the Xcode MCP server
2472. Configure your AI assistant to use the server URL (typically `http://localhost:3000`)
2483. The AI assistant will now have access to all the Xcode tools provided by the server
249 
250### Tool Documentation
251 
252For a comprehensive overview of all available tools and their usage, see [Tools Overview](docs/tools-overview.md).
253 
254For detailed usage examples and best practices, see [User Guide](docs/user-guide.md).
255 
256### Common Workflows
257 
258#### Setting Up a New Project
259 
260```javascript
261// Create a new iOS app project
262await tools.create_xcode_project({
263  name: "MyAwesomeApp",
264  template: "ios-app",
265  outputDirectory: "~/Projects",
266  organizationName: "My Organization",
267  organizationIdentifier: "com.myorganization",
268  language: "swift",
269  includeTests: true,
270  setAsActive: true
271});
272 
273// Add a Swift Package dependency
274await tools.add_swift_package({
275  url: "https://github.com/Alamofire/Alamofire.git",
276  version: "from: 5.0.0"
277});
278```
279 
280#### Working with Files
281 
282```javascript
283// Read a file with specific encoding
284const fileContent = await tools.read_file({
285  filePath: "MyAwesomeApp/AppDelegate.swift",
286  encoding: "utf-8"
287});
288 
289// Write to a file
290await tools.write_file({
291  path: "MyAwesomeApp/NewFile.swift",
292  content: "import Foundation\n\nclass NewClass {}\n",
293  createIfMissing: true
294});
295 
296// Search for text in files
297const searchResults = await tools.search_in_files({
298  directory: "MyAwesomeApp",
299  pattern: "*.swift",
300  searchText: "class",
301  isRegex: false
302});
303```
304 
305#### Building and Testing
306 
307```javascript
308// Build the project
309await tools.build_project({
310  scheme: "MyAwesomeApp",
311  configuration: "Debug"
312});
313 
314// Run tests
315await tools.test_project({
316  scheme: "MyAwesomeApp",
317  testPlan: "MyAwesomeAppTests"
318});
319```
320 
321## Project Structure
322 
323```
324xcode-mcp-server/
325├── src/
326│   ├── index.ts                 # Entry point
327│   ├── server.ts                # MCP server implementation
328│   ├── types/                   # Type definitions
329│   │   └── index.ts             # Core type definitions
330│   ├── utils/                   # Utility functions
331│   │   ├── errors.js            # Error handling classes
332│   │   ├── pathManager.ts       # Path validation and management
333│   │   ├── project.js           # Project utilities
334│   │   └── simulator.js         # Simulator utilities
335│   └── tools/                   # Tool implementations
336│       ├── project/             # Project management tools
337│       │   └── index.ts         # Project creation, detection, file adding
338│       ├── file/                # File operation tools
339│       │   └── index.ts         # File reading, writing, searching
340│       ├── build/               # Build and testing tools
341│       │   └── index.ts         # Building, testing, analyzing
342│       ├── cocoapods/           # CocoaPods integration
343│       │   └── index.ts         # Pod installation and management
344│       ├── spm/                 # Swift Package Manager tools
345│       │   └── index.ts         # Package management and documentation
346│       ├── simulator/           # iOS simulator tools
347│       │   └── index.ts         # Simulator control and interaction
348│       └── xcode/               # Xcode utilities
349│           └── index.ts         # Xcode version management, asset tools
350├── docs/                        # Documentation
351│   ├── tools-overview.md        # Comprehensive tool documentation
352│   └── user-guide.md            # Usage examples and best practices
353├── tests/                       # Tests
354└── dist/                        # Compiled code (generated)
355```
356 
357## How It Works
358 
359The Xcode MCP server uses the Model Context Protocol to provide a standardized interface for AI models to interact with Xcode projects. The server architecture is designed with several key components:
360 
361### Core Components
362 
3631. **Server Implementation**: The main MCP server that handles tool registration and request processing.
364 
3652. **Path Management**: Ensures secure file access by validating all paths against allowed directories.
366 
3673. **Project Management**: Detects, loads, and manages different types of Xcode projects:
368   - Standard Xcode projects (.xcodeproj)
369   - Xcode workspaces (.xcworkspace)
370   - Swift Package Manager projects (Package.swift)
371 
3724. **Directory State**: Maintains the active directory context for relative path resolution.
373 
3745. **Tool Registry**: Organizes tools into logical categories for different Xcode operations.
375 
376### Request Flow
377 
3781. An AI assistant sends a tool execution request to the MCP server.
379 
3802. The server validates the request parameters and permissions.
381 
3823. The appropriate tool handler is invoked with the validated parameters.
383 
3844. The tool executes the requested operation, often using native Xcode commands.
385 
3865. Results are formatted and returned to the AI assistant.
387 
3886. Comprehensive error handling provides meaningful feedback for troubleshooting.
389 
390### Safety Features
391 
392- **Path Validation**: All file operations are restricted to allowed directories.
393- **Error Handling**: Detailed error messages help diagnose issues.
394- **Parameter Validation**: Input parameters are validated using Zod schemas.
395- **Process Management**: External processes are executed safely with proper error handling.
396 
397### Project Type Support
398 
399The server intelligently handles different project types:
400 
401- **Standard Projects**: Direct .xcodeproj manipulation
402- **Workspaces**: Manages multiple projects within a workspace
403- **SPM Projects**: Handles Swift Package Manager specific operations
404 
405This architecture allows AI assistants to seamlessly work with any type of Xcode project while maintaining security and providing detailed feedback.
406 
407## Contributing
408 
409Contributions are welcome! Please feel free to submit a Pull Request.
410 
4111. Fork the repository
4122. Create your feature branch (`git checkout -b feature/amazing-feature`)
4133. Commit your changes (`git commit -m 'Add some amazing feature'`)
4144. Push to the branch (`git push origin feature/amazing-feature`)
4155. Open a Pull Request
416 
417### Development Guidelines
418 
419- Follow the existing code style and organization
420- Add comprehensive error handling with specific error messages
421- Write tests for new functionality
422- Update documentation to reflect your changes
423- Ensure compatibility with different project types (standard, workspace, SPM)
424 
425### Adding New Tools
426 
427To add a new tool to the server:
428 
4291. Identify the appropriate category in the `src/tools/` directory
4302. Implement the tool using the existing patterns with Zod schema validation
4313. Register the tool in the category's `index.ts` file
4324. Add error handling with specific error messages
4335. Document the tool in the appropriate documentation files
434 
435## Troubleshooting
436 
437### Common Issues
438 
439- **Path Access Errors**: Ensure the paths you're trying to access are within the allowed directories
440- **Build Failures**: Check that Xcode command line tools are installed and up to date
441- **Tool Not Found**: Verify that the tool name is correct and properly registered
442- **Parameter Validation Errors**: Check the parameter types and requirements in the tool documentation
443 
444### Debugging
445 
4461. Start the server with debug logging enabled: `npm start -- --debug`
4472. Check the console output for detailed error messages
4483. Examine the server logs for request and response details
4494. For tool-specific issues, try running the equivalent Xcode command directly in the terminal
450 
451## License
452 
453This project is licensed under the MIT License - see the LICENSE file for details.
454 
455## Acknowledgments
456 
457- Thanks to the Model Context Protocol team for the MCP SDK
458- Built with TypeScript and Node.js
459- Uses Xcode command line tools and Swift Package Manager
460- Special thanks to all contributors who have helped improve the server's functionality and robustness
461