Xcode MCP Server

An MCP (Model Context Protocol) server for controlling and interacting with Xcode from AI assistants like Claude.

Features

Get project hierarchy
Build and run projects
Retrieve build errors
Get runtime output (placeholder)
Clean projects

Security

The server implements path-based security to prevent unauthorized access to files outside of allowed directories:

You must specify allowed folders using the environment variable:
- XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3
Otherwise, all files and subfolders from your home directory ($HOME) will be allowed.

Security requirements:

All paths must be absolute (starting with /)
No path components with .. are allowed
All paths must exist and be directories

Example:

# Set the environment variable
export XCODEMCP_ALLOWED_FOLDERS=/Users/username/Projects:/Users/username/checkouts
python3 xcode_mcp.py

# Or inline with the MCP command
XCODEMCP_ALLOWED_FOLDERS=/Users/username/Projects mcp dev xcode_mcp.py

If no allowed folders are specified, access will be restricted and tools will return error messages.

Setup

Configure Claude for Desktop:

First, using homebrew, install 'uv'. You might already have this on your system, but installing it via Homebrew usually ensures that uvx (part of uv) is in the $PATH that Claude Desktop vends to on-device local MCP servers:

brew install uv

Open/create your Claude for Desktop configuration file

Open Claude Desktop --> Settings --> Developer --> Edit Config (to find the file in finder)
It should be at ~/Library/Application Support/Claude/claude_desktop_config.json
Add the following:

{
    "mcpServers": {
        "xcode-mcp-server": {
            "command": "uvx",
            "args": [
                "xcode-mcp-server"
            ]
        }
    }
}

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

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

If you omit the env section, access will default to your $HOME directory.

Add xcode-mcp-server to Claude Code (Anthropic's CLI-based agent)

Install claude code
Add xcode-mcp-server:

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

Add xcode-mcp-server to Cursor AI

Install Cursor, of course
In Cursor, navigate to: Cursor --> Settings --> Cursor Settings
Then choose 'Tools & Integrations'
Tap the + button for 'New MCP Server'

The steps above will get you editing the file ~/.cursor/mcp.json, which you could also edit directly, if you prefer. Add a section for 'xcode-mcp-server' in the 'mcpServers' section - like this:

{
    "mcpServers": {
        "xcode-mcp-server": {
            "command": "uvx",
            "args": [
                "xcode-mcp-server"
            ]
        }
    }
}

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

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

Be sure to hit Command-S to save the file.

If you omit the env section, access will default to your $HOME directory.

Test it out

Open cursor to your favorite xcode project (just open the root folder of the project or git repo), and tell Cursor something like:

build this project using xcode-mcp-server

You'll get a permission prompt from Cursor and then one from macOS, and after that you should be off and running.

Usage

Open Xcode with a project
Start Claude for Desktop
- If xcode-mcp-server failed to initialize properly, you'll see errors
Look for the hammer icon to find available Xcode tools
Use natural language to interact with Xcode, for example:
- "Build the project at /path/to/MyProject.xcodeproj"
- "Run the app in /path/to/MyProject"
- "What build errors are there in /path/to/MyProject.xcodeproj?"
- "Clean the project at /path/to/MyProject"

Parameter Format

All tools require a project_path parameter pointing to an Xcode project/workspace directory:

"/path/to/your/project.xcodeproj"

"/path/to/your/project"

Development

The server is built with the MCP Python SDK and uses AppleScript to communicate with Xcode.

To test the server locally without Claude, use:

# Set the environment variable first
export XCODEMCP_ALLOWED_FOLDERS=/Users/username/Projects
mcp dev xcode_mcp.py

# Or inline with the command
XCODEMCP_ALLOWED_FOLDERS=/Users/username/Projects mcp dev xcode_mcp.py

This will open the MCP Inspector interface where you can test the tools directly.

Testing in MCP Inspector

When testing in the MCP Inspector, provide input values as quoted strings:

"/Users/username/Projects/MyApp"

Limitations

Project hierarchy is a simple file listing implementation
AppleScript syntax may need adjustments for specific Xcode versions # xcode-mcp-server

drewster99/xcode-mcp-server