Skip to main content
Glama
xcode-mcp-server (drewster99)

xcode-mcp-server (drewster99)

by drewster99
README.md
# Drew's Xcode MCP Server (drews-xcode-mcp)

[![PyPI](https://img.shields.io/pypi/v/drews-xcode-mcp.svg)](https://pypi.org/project/drews-xcode-mcp/)
[![Python Versions](https://img.shields.io/pypi/pyversions/drews-xcode-mcp.svg)](https://pypi.org/project/drews-xcode-mcp/)
[![Downloads](https://static.pepy.tech/badge/drews-xcode-mcp)](https://pepy.tech/project/drews-xcode-mcp)
[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
[![macOS Only](https://img.shields.io/badge/platform-macOS-lightgrey)](https://www.apple.com/macos/)
[![Xcode](https://img.shields.io/badge/Xcode-Required-blue)](https://developer.apple.com/xcode/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![GitHub last commit](https://img.shields.io/github/last-commit/drewster99/drews-xcode-mcp)](https://github.com/drewster99/drews-xcode-mcp/commits)

An MCP (Model Context Protocol) server that enables AI assistants to control and interact with Xcode for Apple platform development.

> **Renamed from `xcode-mcp-server`.** With several unrelated projects sharing that
> name — and Xcode itself now shipping a built-in MCP server — this project is now
> `drews-xcode-mcp`. **Existing setups keep working:** the old PyPI name is a
> compatibility package that forwards to this one, and all settings carry over.
> When convenient, update your MCP configuration to run `drews-xcode-mcp`. If your
> server key/name is the old default `xcode-mcp-server`, we recommend renaming it
> to `drews-xcode-mcp` too — just remember to update any tool permission allowlists
> referencing the old tool names (`mcp__xcode-mcp-server__*` becomes
> `mcp__drews-xcode-mcp__*`). If you chose a custom key, keep it and tool
> permissions are unaffected.

## What It Does

This server allows AI assistants (like Claude, Cursor, or other MCP clients) to:

- **Discover and navigate** your Xcode projects and source files
- **Build and run** iOS, macOS, tvOS, and watchOS applications
- **Execute and monitor tests** with detailed results
- **Debug build failures** by retrieving errors and warnings
- **Capture console output** from running applications
- **Take screenshots** of Xcode windows and iOS simulators
- **Manage simulators** and view their status

The AI can perform complete development workflows - from finding a project, to building it, running tests, debugging failures, and capturing results.

## Requirements

- **macOS** - This server only works on macOS
- **Xcode** - Xcode must be installed
- **Python 3.10+** - For running the server (uvx will fetch a compatible Python automatically if your system Python is older)

## Security

The server implements path-based security to control which directories are accessible:

- **With restrictions:** Set `XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3` to limit access to specific directories
- **Default:** If not specified, allows access to your home directory (`$HOME`)

Security requirements:
- All paths must be absolute (starting with `/`)
- No `..` path components allowed
- All paths must exist and be directories

## Setup

First, ensure `uv` is installed (required for all methods below):
```bash
which uv || brew install uv
```

### 1. Claude Code (Recommended)

```bash
claude mcp add --scope user --transport stdio -- drews-xcode-mcp `which uvx` drews-xcode-mcp
```

To run a specific version, use:
```bash
# Example: How to run v1.3.0b6
claude mcp add --scope user --transport stdio -- drews-xcode-mcp `which uvx` drews-xcode-mcp==1.3.0b6
```

That's it! Claude Code handles the rest automatically.

### 2. Claude Desktop

Edit your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
    "mcpServers": {
        "drews-xcode-mcp": {
            "command": "uvx",
            "args": [
                "drews-xcode-mcp"
            ]
        }
    }
}
```

If you'd like to allow only certain projects or folders to be accessible by drews-xcode-mcp, add the `env` option, with a colon-separated list of absolute folder paths, like this:

```json
{
    "mcpServers": {
        "drews-xcode-mcp": {
            "command": "uvx",
            "args": [
                "drews-xcode-mcp"
            ],
            "env": {
                "XCODEMCP_ALLOWED_FOLDERS": "/Users/andrew/my_project:/Users/andrew/Documents/source"
            }
        }
    }
}
```

### 3. Cursor AI

In Cursor: Settings → Tools & Integrations → + New MCP Server

Or edit `~/.cursor/mcp.json` directly:

```json
{
    "mcpServers": {
        "drews-xcode-mcp": {
            "command": "uvx",
            "args": ["drews-xcode-mcp"]
        }
    }
}
```

**Optional:** Add folder restrictions with an `env` section (same format as Claude Desktop above).

## Usage

Once configured, simply ask your AI assistant to help with Xcode tasks:

- "Find all Xcode projects in my home directory"
- "Build the project at /path/to/MyProject.xcodeproj"
- "Run tests for this project and show me any failures"
- "What are the build errors in this project?"
- "Show me the directory structure of this project"
- "Take a screenshot of the Xcode window"

Most tools work with paths to `.xcodeproj` or `.xcworkspace` files, or with regular directory paths for browsing and navigation.

## Advanced Configuration

### Command Line Arguments

When running the server directly (for development or custom setups), these options are available:

**Build output control:**
- `--no-build-warnings` - Show only errors, exclude warnings
- `--always-include-build-warnings` - Always show warnings (default)

**Notifications:**
- `--show-notifications` - Enable macOS notifications for operations
- `--hide-notifications` - Disable notifications (default)

**Access control:**
- `--allowed /path` - Add allowed folder (can be repeated)

Example:
```bash
drews-xcode-mcp --no-build-warnings --show-notifications --allowed ~/Projects
```

**Note:** When using MCP clients (Claude, Cursor), configure these via the `env` section in your client's config file instead.

## Development

The server is built with FastMCP and uses AppleScript to communicate with Xcode.

### Local Testing

Test with MCP Inspector:

```bash
export XCODEMCP_ALLOWED_FOLDERS=~/Projects
mcp dev drews_xcode_mcp/__main__.py
```

This opens an inspector interface where you can test tools directly. Provide paths as quoted strings: `"/Users/you/Projects/MyApp.xcodeproj"`

## Limitations

- AppleScript syntax may need adjustments for specific Xcode versions
- Some operations require the project to be open in Xcode first

TDQS

A4.1/5.0

Scored across 29 tools

Disambiguation4/5

Most tools target distinct operations (build, clean, test, screenshot), though the three run variants (unmonitored, until terminated, with user interaction) and multiple get_build* tools could cause minor confusion if descriptions are not read carefully. Overall, boundaries are clear.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern (e.g., build_project, get_build_errors, list_booted_simulators). Even multi-word verbs like debug_list_notification_history remain readable. No mixed conventions or ambiguous abbreviations.

Tool Count3/5

With 29 tools, the server is on the heavy side. While Xcode development is complex, some tools like version, debug_list_notification_history, and get_directory_listing feel peripheral. The count is justified but pushes the upper bound of reasonable scope.

Completeness4/5

Core workflows are well-covered: build, test, run, clean, destination management, screenshot capture, and error inspection. Minor gaps exist (e.g., no project archiving or code editing), but the surface is sufficient for most development tasks.

Maintenance

ActivityNo data
ResponsivenessOutdated data