Content
# Drew's Xcode MCP Server (drews-xcode-mcp)
[](https://pypi.org/project/drews-xcode-mcp/)
[](https://pypi.org/project/drews-xcode-mcp/)
[](https://pepy.tech/project/drews-xcode-mcp)
[](https://modelcontextprotocol.io)
[](https://www.apple.com/macos/)
[](https://developer.apple.com/xcode/)
[](https://opensource.org/licenses/MIT)
[](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
