Skip to content
Back to search

xcode-mcp-server

MCP Server implementation for Xcode integration

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/r-huijts--xcode-mcp-server/badge.svg)](/listings/r-huijts--xcode-mcp-server)

HTML

<a href="/listings/r-huijts--xcode-mcp-server"><img src="/api/listings/r-huijts--xcode-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- macOS with Xcode 14.0 or higher installed - Node.js 16 or higher - npm or yarn - Swift 5.5+ for Swift Package Manager features - CocoaPods (optional, for CocoaPods integration)

Setup

Option 1: Automated Setup (Recommended)

Use the included setup script which automates the installation and configuration process:

# Make the script executable
chmod +x setup.sh

# Run the setup script
./setup.sh

**What the Setup Script Does:**

1. **Environment Verification**: - Checks that you're running on macOS - Verifies Xcode is installed and accessible - Confirms Node.js (v16+) and npm are available - Checks for Ruby installation - Verifies CocoaPods installation (offers to install if missing)

2. **Dependency Installation**: - Runs `npm install` to install all required Node.js packages - Executes `npm run build` to compile the TypeScript code

3. **Configuration Setup**: - Creates a `.env` file if one doesn't exist - Prompts for your projects base directory - Asks if you want to enable debug logging - Saves your configuration preferences

4. **Claude Desktop Integration** (Optional): - Offers to configure the server for Claude Desktop - Creates or updates the Claude Desktop configuration file - Sets up the proper command and arguments to launch the server

**When to Use the Setup Script:**

- First-time installation to ensure all prerequisites are met - When you want guided configuration with interactive prompts - If you want to quickly set up Claude Desktop integration - To verify your environment has all necessary components

The script will guide you through the configuration process with clear prompts and helpful feedback.

Option 2: Manual Setup

**When to Use Manual Setup:**

- You prefer explicit control over each installation step - You have a custom environment or non-standard configuration - You're setting up in a CI/CD pipeline or automated environment - You want to customize specific aspects of the installation process - You're an experienced developer familiar with Node.js projects

Follow these steps for manual installation:

1. Clone the repository:

   git clone https://github.com/r-huijts/xcode-mcp-server.git
   cd xcode-mcp-server

2. Verify prerequisites (these must be installed): - Xcode and Xcode Command Line Tools - Node.js v16 or higher - npm - Ruby (for CocoaPods support) - CocoaPods (optional, for pod-related features)

3. Install dependencies:

   npm install

4. Build the project:

   npm run build

5. Create a configuration file:

   # Option A: Start with the example configuration
   cp .env.example .env

   # Option B: Create a minimal configuration
   echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
   echo "DEBUG=false" >> .env

Edit the `.env` file to set your preferred configuration.

6. For Claude Desktop integration (optional): - Edit or create `~/Library/Application Support/Claude/claude_desktop_config.json` - Add the following configuration (adjust paths as needed):

   {
     "mcpServers": {
       "xcode": {
         "command": "node",
         "args": ["/path/to/xcode-mcp-server/dist/index.js"]
       }
     }
   }

Setup Troubleshooting

**Common Setup Issues:**

1. **Build Errors**: - Ensure you have the correct Node.js version (v16+) - Try deleting `node_modules` and running `npm install` again - Check for TypeScript errors with `npx tsc --noEmit` - Make sure all imports in the code are properly resolved

2. **Missing Dependencies**: - If you see errors about missing modules, run `npm install` again - For native dependencies, you may need Xcode Command Line Tools: `xcode-select --install`

3. **Permission Issues**: - Ensure you have write permissions to the installation directory - For CocoaPods installation, you may need to use `sudo gem install cocoapods`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 460 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.