https://github.com/cameroncooke/xcodebuildmcp
A Model Context Protocol (MCP) server that provides Xcode-related tools for integration with AI assistants and other MCP clients.
https://github.com/cameroncooke/xcodebuildmcp
mcp mcp-server model-context-protocol model-context-protocol-servers xcode xcodebuild
Last synced: about 1 month ago
JSON representation
A Model Context Protocol (MCP) server that provides Xcode-related tools for integration with AI assistants and other MCP clients.
- Host: GitHub
- URL: https://github.com/cameroncooke/xcodebuildmcp
- Owner: cameroncooke
- License: mit
- Created: 2025-03-09T17:31:18.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-09T14:35:17.000Z (9 months ago)
- Last Synced: 2025-06-09T14:50:49.438Z (9 months ago)
- Topics: mcp, mcp-server, model-context-protocol, model-context-protocol-servers, xcode, xcodebuild
- Language: TypeScript
- Homepage: https://www.async-let.com/blog/xcodebuild-mcp/
- Size: 2.1 MB
- Stars: 1,457
- Watchers: 6
- Forks: 62
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-mcp-servers - XcodeBuildMCP - Popular MCP server that enables AI agents to scaffold, build, run and test iOS, macOS, visionOS and watchOS apps or simulators and wired and wireless devices. It has powerful UI-automation capabilities like controlling the simulator, capturing run-time logs, as well as taking screenshots and viewing the accessibility hierarchy. (Community Servers)
- toolsdk-mcp-registry - ✅ xcodebuildmcp
README
A Model Context Protocol (MCP) server and CLI that provides tools for agent use when working on iOS and macOS projects.
[](https://github.com/cameroncooke/XcodeBuildMCP/actions/workflows/ci.yml)
[](https://badge.fury.io/js/xcodebuildmcp) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://developer.apple.com/xcode/) [](https://www.apple.com/macos/) [](https://modelcontextprotocol.io/) [](https://deepwiki.com/cameroncooke/XcodeBuildMCP)
## Installation
### CLI Installation
```bash
npm install -g xcodebuildmcp@latest
xcodebuildmcp --help
```
### MCP Server Installation
Add XcodeBuildMCP to your MCP client configuration. Most clients use JSON configuration with the following server entry:
```json
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
}
```
Cursor
Recommended (project-scoped): add `.cursor/mcp.json` in your workspace root:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
}
}
}
```
For global Cursor config (`~/.cursor/mcp.json`), use this variant so startup is aligned with the active workspace:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "/bin/zsh",
"args": [
"-lc",
"cd \"${workspaceFolder}\" && exec npx -y xcodebuildmcp@latest mcp"
]
}
}
}
```
Or use the quick install link:
[](https://cursor.com/en-US/install-mcp?name=XcodeBuildMCP&config=eyJjb21tYW5kIjoibnB4IC15IHhjb2RlYnVpbGRtY3BAbGF0ZXN0IG1jcCJ9)
Claude Code
Run:
```bash
claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
```
Codex CLI
Run:
```bash
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp
```
Or add to `~/.codex/config.toml`:
```toml
[mcp_servers.XcodeBuildMCP]
command = "npx"
args = ["-y", "xcodebuildmcp@latest", "mcp"]
```
Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
}
}
}
```
VS Code / VS Code Insiders
Add to your VS Code settings JSON:
```json
"mcp": {
"servers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
}
}
}
```
Or use the quick install links:
[](vscode:mcp/install?%7B%22name%22%3A%22XcodeBuildMCP%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%2C%22mcp%22%5D%7D)
[](vscode-insiders:mcp/install?%7B%22name%22%3A%22XcodeBuildMCP%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%2C%22mcp%22%5D%7D)
Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
}
}
}
```
Trae
Add to `~/Library/Application Support/Trae/User/mcp.json`:
```json
{
"mcpServers": {
"XcodeBuildMCP": {
"command": "npx",
"args": ["-y", "xcodebuildmcp@latest", "mcp"]
}
}
}
```
Xcode (Codex Agent)
Requires Xcode 26.3 or later. Codex agent must be installed and configured in Xcode Settings -> Intelligence -> Open AI.
The only way at the time of writing to add an MCP server is to use a project scoped `.codex/config.toml` file in the root of your project workspace:
`/path/to/your/project/.codex/config.toml`
```toml
[mcp_servers.XcodeBuildMCP]
args = [
"-lc",
"PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; export NVM_DIR=\"$HOME/.nvm\"; [ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"; nvm use --silent >/dev/null 2>&1 || true; npx -y xcodebuildmcp@latest mcp"
]
command = "/bin/zsh"
enabled = true
tool_timeout_sec = 10000
```
> **NOTE**:
> Codex Agent when running in Xcode has a limited PATH by default. The above example should work for most users but if you find the server doesn't start or is not available, it's likely because npx is not found so you might have to adjust the above configuration accordingly.
Xcode (Claude Code Agent)
Requires Xcode 26.3 or later. Claude Code agent must be installed and configured in Xcode Settings -> Intelligence -> Anthropic.
Add to the end or replace the existing `mcpServers` object in Xcode's Claude Code agent config at:
`~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude.json`
```json
// ... rest of file ...
"mcpServers": {
"XcodeBuildMCP": {
"command": "/bin/zsh",
"args": [
"-lc",
"PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin; export NVM_DIR=\"$HOME/.nvm\"; [ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"; nvm use --silent >/dev/null 2>&1 || true; npx -y xcodebuildmcp@latest mcp"
]
}
}
}
```
> **NOTE**:
> Claude Code Agent when running in Xcode has a limited PATH by default. The above example should work for most users but if you find the server doesn't start or is not available, it's likely because npx is not found so you might have to adjust the above configuration accordingly.
For other installation options see [Getting Started](docs/GETTING_STARTED.md)
When configuring a client manually, ensure the command includes the `mcp` subcommand (for example, `npx -y xcodebuildmcp@latest mcp`).
## Requirements
- macOS 14.5 or later
- Xcode 16.x or later
- Node.js 18.x or later
## Skills
XcodeBuildMCP now includes two optional agent skills:
- **MCP Skill**: Primes the agent with instructions on how to use the MCP server's tools (optional when using the MCP server).
- **CLI Skill**: Primes the agent with instructions on how to navigate the CLI (recommended when using the CLI).
To install, copy and paste the command below into a terminal and follow the on-screen instructions.
```bash
curl -fsSL https://raw.githubusercontent.com/cameroncooke/XcodeBuildMCP/v2.0.0/scripts/install-skill.sh -o install-skill.sh && bash install-skill.sh
```
For further information on how to install the skill, see: [docs/SKILLS.md](docs/SKILLS.md)
## Notes
- XcodeBuildMCP requests xcodebuild to skip macro validation to avoid errors when building projects that use Swift Macros.
- Device tools require code signing to be configured in Xcode. See [docs/DEVICE_CODE_SIGNING.md](docs/DEVICE_CODE_SIGNING.md).
## Privacy
XcodeBuildMCP uses Sentry for error telemetry. For more information or to opt out of error telemetry see [docs/PRIVACY.md](docs/PRIVACY.md).
## CLI
XcodeBuildMCP provides a unified command-line interface. The `mcp` subcommand starts the MCP server, while all other commands provide direct terminal access to tools:
```bash
# Install globally
npm install -g xcodebuildmcp@latest
# Start the MCP server (for MCP clients)
xcodebuildmcp mcp
# List available tools
xcodebuildmcp tools
# Build for simulator
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj
```
The CLI uses a per-workspace daemon for stateful operations (log capture, debugging, etc.) that auto-starts when needed. See [docs/CLI.md](docs/CLI.md) for full documentation.
## Documentation
- Getting started: [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)
- CLI usage: [docs/CLI.md](docs/CLI.md)
- Configuration and options: [docs/CONFIGURATION.md](docs/CONFIGURATION.md)
- Tools reference: [docs/TOOLS.md](docs/TOOLS.md)
- Troubleshooting: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
- Privacy: [docs/PRIVACY.md](docs/PRIVACY.md)
- Skills: [docs/SKILLS.md](docs/SKILLS.md)
- Contributing: [docs/dev/CONTRIBUTING.md](docs/dev/CONTRIBUTING.md)
## Licence
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.