xcode-mcp-server (drewster99)

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:

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:

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:

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:

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:

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:

or

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:

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:

Limitations

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