# 🔨 Xcode MCP Server

> **The first MCP server for Xcode** — Let AI agents like Claude build your iOS apps!

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)
[![Platform](https://img.shields.io/badge/Platform-macOS-lightgrey.svg)](https://developer.apple.com/xcode/)

An MCP (Model Context Protocol) server that gives AI assistants the power to work with Xcode projects. List projects, read configurations, inspect targets, and trigger builds — all through natural conversation.

## ✨ Features

| Tool | Description |
|------|-------------|
| `list-projects` | Find all Xcode projects in a directory tree |
| `read-project` | Parse .xcodeproj structure (targets, configs, files) |
| `list-targets` | Get build targets with product types |
| `list-schemes` | List available build schemes |
| `build` | Trigger xcodebuild with configurable options |
| `xcodebuild-info` | Get Xcode version and available SDKs |

## 🚀 Quick Start

### Prerequisites

- macOS with Xcode Command Line Tools (`xcode-select --install`)
- Node.js 18+
- npm or yarn

### Installation

```bash
# Clone the repo
git clone https://github.com/airdrop-alpha/xcode-mcp.git
cd xcode-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build
```

### Configuration

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

#### OpenClaw

Add to your OpenClaw MCP config:

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

## 💬 Example Conversation

```
You: List Xcode projects in my Developer folder

Claude: Found 3 Xcode projects:
  • MyApp.xcodeproj
  • TestFramework.xcodeproj
  • SampleProject.xcodeproj

You: What targets does MyApp have?

Claude: MyApp has 3 targets:
  • MyApp (application)
  • MyAppTests (unit-test)
  • MyAppUITests (ui-test)

You: Build it for iPhone 15 simulator

Claude: ✅ Build succeeded!
```

## 🛠️ Tool Reference

### list-projects

Find Xcode projects in a directory (recursive, 5 levels deep).

```json
{ "directory": "/path/to/search" }
```

### read-project

Parse an Xcode project file and return its structure.

```json
{ "projectPath": "/path/to/MyApp.xcodeproj" }
```

**Returns:** Project name, targets, build configurations, source files.

### list-targets

List build targets with their product types.

```json
{ "projectPath": "/path/to/MyApp.xcodeproj" }
```

**Returns:** Target names and types (app, framework, test, etc.)

### list-schemes

List available schemes (shared and user).

```json
{ "projectPath": "/path/to/MyApp.xcodeproj" }
```

### build

Build a project using xcodebuild.

```json
{
  "projectPath": "/path/to/MyApp.xcodeproj",
  "scheme": "MyApp",
  "configuration": "Debug",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "clean": false
}
```

### xcodebuild-info

Get Xcode version and SDK information. No parameters required.

## 🏗️ Architecture

```
xcode-mcp/
├── src/
│   ├── index.ts         # MCP server entry point
│   └── xcode-parser.ts  # Xcode project file parser
├── dist/                # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

## ⚠️ Current Limitations

- Parses `.xcodeproj` files directly (simplified parser)
- `.xcworkspace` support coming soon
- Build output truncated to last 5KB for large projects
- Code signing disabled by default for faster builds

## 🗺️ Roadmap

- [ ] Workspace (`.xcworkspace`) support
- [ ] Simulator management (list, boot, install)
- [ ] Test execution with result parsing
- [ ] Swift Package dependencies
- [ ] Provisioning profile management
- [ ] App Store Connect integration

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

```bash
# Development mode (hot reload)
npm run dev

# Test with MCP Inspector
npm run inspect
```

## 📄 License

[MIT](LICENSE) © 2026

---

**Built for the AI-assisted development era. 🤖**