# 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:/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 -- xcode-mcp-server `which uvx` xcode-mcp-server
```
To run a specific version, use:
```bash
# 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`):
```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:
```json
{
"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:
```json
{
"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:
```bash
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:
```bash
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
Raw data
{
"_id": null,
"home_page": null,
"name": "xcode-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, server, xcode",
"author": null,
"author_email": "Andrew Benson <db@nuclearcyborg.com>",
"download_url": "https://files.pythonhosted.org/packages/c8/57/a635676669e8fc0b2ac042f4753a7eff55a9d9118aadca6b393fc07940d1/xcode_mcp_server-1.3.1.tar.gz",
"platform": null,
"description": "# Xcode MCP Server\n\nAn MCP (Model Context Protocol) server that enables AI assistants to control and interact with Xcode for Apple platform development.\n\n## What It Does\n\nThis server allows AI assistants (like Claude, Cursor, or other MCP clients) to:\n\n- **Discover and navigate** your Xcode projects and source files\n- **Build and run** iOS, macOS, tvOS, and watchOS applications\n- **Execute and monitor tests** with detailed results\n- **Debug build failures** by retrieving errors and warnings\n- **Capture console output** from running applications\n- **Take screenshots** of Xcode windows and iOS simulators\n- **Manage simulators** and view their status\n\nThe AI can perform complete development workflows - from finding a project, to building it, running tests, debugging failures, and capturing results.\n\n## Requirements\n\n- **macOS** - This server only works on macOS\n- **Xcode** - Xcode must be installed\n- **Python 3.8+** - For running the server\n\n## Security\n\nThe server implements path-based security to control which directories are accessible:\n\n- **With restrictions:** Set `XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3` to limit access to specific directories\n- **Default:** If not specified, allows access to your home directory (`$HOME`)\n\nSecurity requirements:\n- All paths must be absolute (starting with `/`)\n- No `..` path components allowed\n- All paths must exist and be directories\n\n## Setup\n\nFirst, ensure `uv` is installed (required for all methods below):\n```bash\nwhich uv || brew install uv\n```\n\n### 1. Claude Code (Recommended)\n\n```bash\nclaude mcp add --scope user --transport stdio -- xcode-mcp-server `which uvx` xcode-mcp-server\n```\n\nTo run a specific version, use:\n```bash\n# Example: How to run v1.3.0b6\nclaude mcp add --scope user --transport stdio -- xcode-mcp-server `which uvx` xcode-mcp-server==1.3.0b6\n```\n\nThat's it! Claude Code handles the rest automatically.\n\n### 2. Claude Desktop\n\nEdit your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"xcode-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\n \"xcode-mcp-server\"\n ]\n }\n }\n}\n```\n\nIf 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:\n\n```json\n{\n \"mcpServers\": {\n \"xcode-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\n \"xcode-mcp-server\"\n ],\n \"env\": {\n \"XCODEMCP_ALLOWED_FOLDERS\": \"/Users/andrew/my_project:/Users/andrew/Documents/source\"\n }\n }\n }\n}\n```\n\n### 3. Cursor AI\n\nIn Cursor: Settings \u2192 Tools & Integrations \u2192 + New MCP Server\n\nOr edit `~/.cursor/mcp.json` directly:\n\n```json\n{\n \"mcpServers\": {\n \"xcode-mcp-server\": {\n \"command\": \"uvx\",\n \"args\": [\"xcode-mcp-server\"]\n }\n }\n}\n```\n\n**Optional:** Add folder restrictions with an `env` section (same format as Claude Desktop above).\n\n## Usage\n\nOnce configured, simply ask your AI assistant to help with Xcode tasks:\n\n- \"Find all Xcode projects in my home directory\"\n- \"Build the project at /path/to/MyProject.xcodeproj\"\n- \"Run tests for this project and show me any failures\"\n- \"What are the build errors in this project?\"\n- \"Show me the directory structure of this project\"\n- \"Take a screenshot of the Xcode window\"\n\nMost tools work with paths to `.xcodeproj` or `.xcworkspace` files, or with regular directory paths for browsing and navigation.\n\n## Advanced Configuration\n\n### Command Line Arguments\n\nWhen running the server directly (for development or custom setups), these options are available:\n\n**Build output control:**\n- `--no-build-warnings` - Show only errors, exclude warnings\n- `--always-include-build-warnings` - Always show warnings (default)\n\n**Notifications:**\n- `--show-notifications` - Enable macOS notifications for operations\n- `--hide-notifications` - Disable notifications (default)\n\n**Access control:**\n- `--allowed /path` - Add allowed folder (can be repeated)\n\nExample:\n```bash\nxcode-mcp-server --no-build-warnings --show-notifications --allowed ~/Projects\n```\n\n**Note:** When using MCP clients (Claude, Cursor), configure these via the `env` section in your client's config file instead.\n\n## Development\n\nThe server is built with FastMCP and uses AppleScript to communicate with Xcode.\n\n### Local Testing\n\nTest with MCP Inspector:\n\n```bash\nexport XCODEMCP_ALLOWED_FOLDERS=~/Projects\nmcp dev xcode_mcp_server/__main__.py\n```\n\nThis opens an inspector interface where you can test tools directly. Provide paths as quoted strings: `\"/Users/you/Projects/MyApp.xcodeproj\"`\n\n## Limitations\n\n- AppleScript syntax may need adjustments for specific Xcode versions\n- Some operations require the project to be open in Xcode first\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Drew's MCP server for Xcode integration",
"version": "1.3.1",
"project_urls": {
"Homepage": "https://github.com/drewster99/xcode-mcp-server",
"Issues": "https://github.com/drewster99/xcode-mcp-server/issues",
"Repository": "https://github.com/drewster99/xcode-mcp-server"
},
"split_keywords": [
"mcp",
" server",
" xcode"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6c1420fe8b147d5d1f2f0523bef3b1e7d3bf5f1d05abd712baf9b7c48083b212",
"md5": "07be8dfee6f0efef518f4092ae3f45e2",
"sha256": "73e2720cc870ee29821723a709ff1bd948928b5d7b8b343a2948535248921ad0"
},
"downloads": -1,
"filename": "xcode_mcp_server-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "07be8dfee6f0efef518f4092ae3f45e2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 80782,
"upload_time": "2025-10-15T14:48:16",
"upload_time_iso_8601": "2025-10-15T14:48:16.151798Z",
"url": "https://files.pythonhosted.org/packages/6c/14/20fe8b147d5d1f2f0523bef3b1e7d3bf5f1d05abd712baf9b7c48083b212/xcode_mcp_server-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c857a635676669e8fc0b2ac042f4753a7eff55a9d9118aadca6b393fc07940d1",
"md5": "c77581a2b48134a8662b2a6a61ad3cb0",
"sha256": "d7f83aa0ff61d7ca9ab9de36229d4ef278311a46c44c9c5eb588a1b704ab2c96"
},
"downloads": -1,
"filename": "xcode_mcp_server-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c77581a2b48134a8662b2a6a61ad3cb0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4846700,
"upload_time": "2025-10-15T14:48:18",
"upload_time_iso_8601": "2025-10-15T14:48:18.922111Z",
"url": "https://files.pythonhosted.org/packages/c8/57/a635676669e8fc0b2ac042f4753a7eff55a9d9118aadca6b393fc07940d1/xcode_mcp_server-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-15 14:48:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "drewster99",
"github_project": "xcode-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.2.0"
]
]
},
{
"name": "questionary",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
}
],
"lcname": "xcode-mcp-server"
}
JSON
