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

./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.

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:

cp .env.example .env

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"]

       }

     }

   }

   

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

4. Configuration Problems:
- Verify your .env file has the correct format and valid paths
- Make sure PROJECTS_BASE_DIR points to an existing directory
- Check that the path doesn't contain special characters that need escaping

5. Claude Desktop Integration:
- Ensure the path in the Claude configuration points to the correct location of index.js
- Restart Claude Desktop after making configuration changes
- Check that the server is running before attempting to use it with Claude

You can configure the server in two ways:

1. Environment variables in .env file:

   PROJECTS_BASE_DIR=/path/to/your/projects

   DEBUG=true

   ALLOWED_PATHS=/path/to/additional/allowed/directory

   PORT=8080

   

2. Command line arguments:

   npm start -- --projects-dir=/path/to/your/projects --port=8080

   

- PROJECTS_BASE_DIR / --projects-dir: Base directory for projects (required)
- ALLOWED_PATHS / --allowed-paths: Additional directories to allow access to (comma-separated)
- PORT / --port: Port to run the server on (default: 3000)
- DEBUG / --debug: Enable debug logging (default: false)
- LOG_LEVEL / --log-level: Set logging level (default: info)