Xcode MCP Server
An MCP (Model Context Protocol) server that enables AI assistants to control and interact with Xcode for Apple platform development.
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.8+ - For running the server
Security
The server implements path-based security to control which directories are accessible:
- With restrictions: Set
XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3to 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):
which uv || brew install uv
1. Claude Code (Recommended)
claude mcp add --scope user --transport stdio -- xcode-mcp-server `which uvx` xcode-mcp-server
To run a specific version, use:
# Example: How to run v1.3.0b6
claude mcp add --scope user --transport stdio -- xcode-mcp-server `which uvx` xcode-mcp-server==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):
{
"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"
}
}
}
}
3. Cursor AI
In Cursor: Settings → Tools & Integrations → + New MCP Server
Or edit ~/.cursor/mcp.json directly:
{
"mcpServers": {
"xcode-mcp-server": {
"command": "uvx",
"args": ["xcode-mcp-server"]
}
}
}
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:
xcode-mcp-server --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:
export XCODEMCP_ALLOWED_FOLDERS=~/Projects
mcp dev xcode_mcp_server/__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