# MCP Xcode Server
An MCP (Model Context Protocol) server that provides tools for interacting with Xcode projects programmatically.
## Installation
Clone this repository:
```bash
git clone https://github.com/chacebot/mcp-xcode-server.git
cd mcp-xcode-server
npm install
```
Or install from a local directory:
```bash
cd /path/to/mcp-xcode-server
npm install
```
## Features
This server provides the following tools for Xcode project management:
- **xcode_read_project** - Read and parse Xcode project files
- **xcode_list_schemes** - List all build schemes in a project
- **xcode_list_targets** - List all targets in a project
- **xcode_add_test_target** - Add a test target to a project
- **xcode_configure_test_target** - Configure a test target for a project
- **xcode_add_file_to_target** - Add files to project targets
- **xcode_remove_file_from_target** - Remove files from project targets
- **xcode_list_files_in_target** - List all files in a target
- **xcode_build** - Build Xcode projects
- **xcode_test** - Run tests in Xcode projects
- **xcode_get_build_settings** - Get build settings
- **xcode_get_build_errors** - Get and parse build errors
- **xcode_clean** - Clean build artifacts
- **xcode_validate_project** - Validate project structure and check for issues
## Quick Start
1. **Install dependencies:**
```bash
npm install
```
2. **Configure your MCP client** (Claude Desktop, Cursor, etc.):
```json
{
"mcpServers": {
"xcode": {
"command": "node",
"args": ["/absolute/path/to/mcp-xcode-server/src/index.js"],
"env": {}
}
}
}
```
3. **Restart your MCP client** to load the server
4. **Start using Xcode tools** through your AI assistant!
See [QUICKSTART.md](./QUICKSTART.md) for a 5-minute setup guide, or [SETUP.md](./SETUP.md) for detailed instructions.
## Usage
### As an MCP Server
Configure this server in your MCP client configuration. For example, in Claude Desktop or Cursor:
```json
{
"mcpServers": {
"xcode": {
"command": "node",
"args": ["/path/to/mcp-xcode-server/src/index.js"],
"env": {}
}
}
}
```
### Standalone Testing
You can test the server directly:
```bash
npm start
```
The server communicates via stdio using the MCP protocol.
## Requirements
- Node.js 18+
- Xcode command-line tools installed
- Access to Xcode projects
## Tools Reference
### xcode_read_project
Read and parse an Xcode project file to extract its structure.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
**Example:**
```json
{
"name": "xcode_read_project",
"arguments": {
"projectPath": "/path/to/Project.xcodeproj"
}
}
```
### xcode_list_schemes
List all build schemes available in the project.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
### xcode_list_targets
List all targets in the project.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
### xcode_add_test_target
Add a new test target to the project. Note: This currently provides instructions rather than directly modifying the pbxproj file, as that requires careful parsing and manipulation.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `targetName` (optional): Name for the test target (defaults to ProjectNameTests)
### xcode_add_file_to_target
Add a file to a specific target in the project.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `filePath` (required): Relative path to the file from project root
- `targetName` (required): Name of the target
### xcode_build
Build the Xcode project using xcodebuild.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Build scheme name
- `configuration` (optional): Debug or Release (default: Debug)
### xcode_test
Run tests in the Xcode project.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Test scheme name
### xcode_get_build_settings
Get build settings for the project or a specific scheme.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Scheme name
- `configuration` (optional): Debug or Release (default: Debug)
### xcode_clean
Clean build artifacts from the project.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Build scheme name
### xcode_remove_file_from_target
Remove a file from an Xcode project target.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `filePath` (required): Relative path to the file from project root
- `targetName` (required): Name of the target
### xcode_get_build_errors
Get build errors from the last build attempt. Parses xcodebuild output to extract error messages.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Build scheme name
### xcode_list_files_in_target
List all files in a specific target.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `targetName` (required): Name of the target
### xcode_validate_project
Validate Xcode project structure and check for common issues like missing targets, schemes, or configuration problems.
**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
## Limitations
- The pbxproj parser is simplified and may not handle all edge cases
- Adding targets/files requires careful manipulation of the pbxproj format
- Some operations may require Xcode to be installed and properly configured
## Future Improvements
- Full pbxproj parser using a proper library (e.g., `xcode` npm package)
- Better error handling and validation
- Support for Xcode workspaces (.xcworkspace)
- Support for Swift Package Manager integration
- Support for modifying build settings
- Support for managing code signing
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin feature/my-feature`
5. Submit a pull request
## License
MIT - see [LICENSE](./LICENSE) file for details
