Xcode-mcp-server (drewster99)

Enable Claude Code, Cursor or your favorite LLM tool to command Xcode to build your projects, automatically get back build errors, or more. Huge productivity increase and you keep using the tools you're used to.

Installation Instructions

README: https://github.com/drewster99/xcode-mcp-server

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

1. 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.

2. 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

3. 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

1. Open Xcode with a project
2. Start Claude for Desktop
   • If xcode-mcp-server failed to initialize properly, you'll see errors
3. Look for the hammer icon to find available Xcode tools
4. 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"

or

"/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