{
"markdown": "> **Using with Apple's Official Xcode MCP**: Apple now provides an [official Xcode MCP server](https://developer.apple.com/documentation/xcode/giving-agentic-coding-tools-access-to-xcode). XcodeMCP can run alongside it in **sidekick mode** (`--sidekick-only`), providing complementary tools like project management and XCResult analysis. In a future version, XcodeMCP will transition to sidekick-only mode by default. [See configuration below](#sidekick-mode).\n\n# XcodeMCP\n\n[](https://www.npmjs.com/package/xcodemcp)\n[](https://github.com/lapfelix/XcodeMCP/actions/workflows/test.yml)\n\nModel Context Protocol (MCP) server that controls Xcode directly through JavaScript for Automation (JXA). Available as both an MCP server and a standalone CLI.\n\n## What it does\n\n- Controls Xcode directly through JavaScript for Automation (not xcodebuild CLI)\n- Opens projects, builds, runs, tests, and debugs from within Xcode\n- Parses build logs with precise error locations using [XCLogParser](https://github.com/MobileNativeFoundation/XCLogParser)\n- Provides comprehensive environment validation and health checks\n- Supports graceful degradation when optional dependencies are missing\n- **NEW**: Includes a full-featured CLI with 100% MCP server feature parity\n\n## Requirements\n\n- macOS with Xcode installed\n- Node.js 18+\n- XCLogParser (recommended): `brew install xclogparser`\n\n## Usage\n\nXcodeMCP can be used in two ways:\n1. **MCP Server**: Integrate with Claude Desktop, VS Code, or other MCP clients\n2. **CLI Tool**: Run commands directly from the terminal with `xcodecontrol`\n\n### Quick Install\n\n[![\"Install](\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF\")
](https://insiders.vscode.dev/redirect/mcp/install?name=xcodemcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22xcodemcp%40latest%22%5D%7D)\n[![\"Install](\"https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5\")
](https://insiders.vscode.dev/redirect/mcp/install?name=xcodemcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22xcodemcp%40latest%22%5D%7D&quality=insiders)\n[![\"Install](\"https://cursor.com/deeplink/mcp-install-dark.svg\")
](https://cursor.com/install-mcp?name=XcodeMCP&config=eyJjb21tYW5kIjoibnB4IHhjb2RlbWNwQGxhdGVzdCIsImVudiI6e319)\n\nXCLogParser is recommended but optional:\n```bash\nbrew install xclogparser\n```\n\n### Install from npm\n\nRun directly with npx:\n```bash\nnpx -y xcodemcp@latest\n```\n\nOr install globally:\n```bash\nnpm install -g xcodemcp\n```\n\n### MCP Configuration\n\nAdd to your MCP configuration:\n```json\n{\n \"mcpServers\": {\n \"xcodemcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"xcodemcp@latest\"],\n \"env\": {\n }\n }\n }\n}\n```\n\n### Claude Code CLI Setup\n\nTo add XcodeMCP to Claude Code using the command line:\n```bash\nclaude mcp add-json XcodeMCP '{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"xcodemcp@latest\"],\n \"env\": {\n }\n}'\n```\n\n#### Without the clean build folder tool\n\nTo add XcodeMCP to Claude Code using the command line:\n```bash\nclaude mcp add-json XcodeMCP '{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"xcodemcp@latest\", \"--no-clean\"],\n \"env\": {\n }\n}'\n```\n\n#### Using Preferred Values for Single Project Workflows\n\nFor projects where you're working with a single xcodeproj and scheme, you can configure preferred values to make tool parameters optional:\n\n```bash\nclaude mcp add-json XcodeMCP '{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"xcodemcp@latest\"],\n \"env\": {\n \"XCODE_MCP_PREFERRED_SCHEME\": \"MyApp\",\n \"XCODE_MCP_PREFERRED_XCODEPROJ\": \"MyApp.xcodeproj\"\n }\n}'\n```\n\nWith preferred values configured:\n- Tool parameters become optional instead of required\n- Tool descriptions show default values (e.g., \"defaults to MyApp.xcodeproj\")\n- You can still override defaults by providing explicit parameters\n- Reduces repetition when working with a single project\n\n#### Troubleshooting\n\nIf `/mcp` in Claude Code indicates the MCP failed, try running it from the project folder manually to see what the output is: `npx -y xcodemcp@latest`\n\n### Sidekick Mode\n\nWhen using XcodeMCP alongside [Apple's official Xcode MCP server](https://developer.apple.com/documentation/xcode/giving-agentic-coding-tools-access-to-xcode), enable sidekick mode to only include complementary tools:\n\n- **Project management**: Open/close projects, manage schemes, workspace info\n- **XCResult analysis**: Browse test results, extract screenshots, inspect UI hierarchies\n\nThis excludes build/run/test/debug tools that Apple's MCP handles natively.\n\n#### Claude Code CLI Setup (Both Servers)\n\nFirst, enable Xcode Tools in Xcode > Settings > Intelligence > Model Context Protocol.\n\nThen add both Apple's Xcode MCP and XcodeMCP in sidekick mode:\n```bash\n# Add Apple's official Xcode MCP\nclaude mcp add --transport stdio xcode -- xcrun mcpbridge\n\n# Add XcodeMCP in sidekick mode (project management + XCResult analysis)\nclaude mcp add-json xcodemcp '{\"command\": \"npx\", \"args\": [\"-y\", \"xcodemcp@latest\", \"--sidekick-only\"]}'\n```\n\n#### JSON Configuration (Both Servers)\n\n```json\n{\n \"mcpServers\": {\n \"xcode\": {\n \"command\": \"xcrun\",\n \"args\": [\"mcpbridge\"]\n },\n \"xcodemcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"xcodemcp@latest\", \"--sidekick-only\"]\n }\n }\n}\n```\n\n> **Future direction**: In a future version, XcodeMCP will transition to sidekick-only mode by default, focusing exclusively on tools that complement Apple's official Xcode MCP rather than duplicating functionality.\n\n### Development Setup\n\nFor local development:\n```bash\ngit clone https://github.com/lapfelix/XcodeMCP.git\ncd XcodeMCP\nnpm install\n\n# Run in development mode (TypeScript)\nnpm run dev:ts\n\n# Or build and run compiled version\nnpm run build\nnpm start\n```\n\n## CLI Usage\n\nXcodeMCP includes a powerful CLI that provides 100% feature parity with the MCP server, allowing you to run any tool as a one-shot command:\n\n### Installation\n\nInstall globally to use the CLI:\n```bash\nnpm install -g xcodemcp\n```\n\n### Basic Usage\n\n```bash\n# Show help and available tools\nxcodecontrol --help\n\n# Run a tool with flags \nxcodecontrol build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme\n\n# Get help for a specific tool\nxcodecontrol build --help\n\n# Use JSON input instead of flags\nxcodecontrol build --json-input '{\"xcodeproj\": \"/path/to/Project.xcodeproj\", \"scheme\": \"MyScheme\"}'\n\n# Output results in JSON format\nxcodecontrol --json health-check\n```\n\n### Path Resolution\n\nThe CLI supports both absolute and relative paths for convenience:\n\n```bash\n# Absolute paths (traditional)\nxcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp\n\n# Relative paths (NEW in v2.0.0)\nxcodecontrol build --xcodeproj MyApp.xcodeproj --scheme MyApp\nxcodecontrol build --xcodeproj ../OtherProject/OtherProject.xcodeproj --scheme OtherApp\n\n# Works with file paths too\nxcodecontrol open-file --filePath src/ViewController.swift --lineNumber 42\n```\n\nRelative paths are resolved from your current working directory, making the CLI much more convenient to use when working within project directories.\n\n### Verbosity Control\n\nControl logging output with verbosity flags:\n\n```bash\n# Verbose mode (shows INFO and DEBUG logs)\nxcodecontrol -v build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme\n\n# Quiet mode (only errors)\nxcodecontrol -q test --xcodeproj /path/to/Project.xcodeproj\n\n# Default mode (warnings and errors only)\nxcodecontrol run --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme\n```\n\n### Quick Examples\n\n```bash\n# Check system health\nxcodecontrol health-check\n\n# Build a project\nxcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp\n\n# Run the app\nxcodecontrol run --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp\n\n# Run tests\nxcodecontrol test --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj\n\n# Clean build directory\nxcodecontrol clean --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj\n\n# Browse XCResult files\nxcodecontrol xcresult-browse --xcresult-path /path/to/result.xcresult\n\n# Get UI hierarchy from test failure\nxcodecontrol xcresult-get-ui-hierarchy --xcresult-path /path/to/result.xcresult --test-id \"MyTest/testMethod()\" --timestamp 30.5\n```\n\n### Tool Name Mapping\n\nCLI commands use kebab-case instead of underscores:\n- `xcode_build` → `build`\n- `xcode_test` → `test` \n- `xcode_build_and_run` → `build-and-run`\n- `xcode_health_check` → `health-check`\n- `xcresult_browse` → `xcresult-browse`\n- `find_xcresults` → `find-xcresults`\n\n## Available Tools\n\n**Project Management:**\n- `xcode_open_project` - Open projects and workspaces\n- `xcode_get_workspace_info` - Get workspace status and details\n- `xcode_get_projects` - List projects in workspace\n- `xcode_open_file` - Open files with optional line number\n\n**Build Operations:**\n- `xcode_build` - Build with detailed error parsing\n- `xcode_clean` - Clean build artifacts\n- `xcode_test` - Run tests with optional arguments\n- `xcode_build_and_run` - Build and run the active scheme\n- `xcode_debug` - Start debugging session\n- `xcode_stop` - Stop current operation\n\n**Configuration:**\n- `xcode_get_schemes` - List available schemes\n- `xcode_set_active_scheme` - Switch active scheme\n- `xcode_get_run_destinations` - List simulators and devices\n\n**XCResult Analysis:**\n- `xcresult_browse` - Browse test results and analyze failures\n- `xcresult_browser_get_console` - Get console output for specific tests\n- `xcresult_summary` - Quick overview of test results\n- `xcresult_get_screenshot` - Extract screenshots from test failures\n- `xcresult_get_ui_hierarchy` - Get UI hierarchy as AI-readable JSON with timestamp selection\n- `xcresult_get_ui_element` - Get detailed properties of specific UI elements by index\n- `xcresult_list_attachments` - List all attachments for a test\n- `xcresult_export_attachment` - Export specific attachments from test results\n\n**Diagnostics:**\n- `xcode_health_check` - Environment validation and troubleshooting\n\n## XCResult Analysis Features\n\nXcodeMCP provides comprehensive tools for analyzing Xcode test results (.xcresult files), making it easy to debug test failures and extract valuable information:\n\n### Test Result Analysis\n- **Browse Results**: Navigate through test hierarchies, view pass/fail status, and examine detailed test information\n- **Console Logs**: Extract console output and test activities with precise timestamps for debugging\n- **Quick Summaries**: Get overview statistics including pass rates, failure counts, and duration\n\n### Visual Debugging\n- **Screenshot Extraction**: Extract PNG screenshots from test failures using ffmpeg frame extraction from video attachments\n- **Timestamp Precision**: Specify exact timestamps to capture UI state at specific moments during test execution\n\n### UI Hierarchy Analysis\n- **AI-Readable Format**: Extract UI hierarchies as compressed JSON with single-letter properties (`t`=type, `l`=label, `f`=frame, `c`=children, `j`=index)\n- **Timestamp Selection**: Automatically find the closest UI hierarchy capture to any specified timestamp\n- **Element Deep-Dive**: Use index references to get full details of any UI element, including accessibility properties and frame information\n- **Size Optimization**: 75%+ size reduction compared to full hierarchy data while maintaining all essential information\n\n### Attachment Management\n- **Complete Inventory**: List all attachments (screenshots, videos, debug descriptions, UI hierarchies) for any test\n- **Selective Export**: Export specific attachments by index or type\n- **Smart Detection**: Automatically identify and categorize different attachment types\n\n### Usage Examples\n\n```bash\n# Browse test results\nxcresult_browse \"/path/to/TestResults.xcresult\"\n\n# Get console output to find failure timestamps\nxcresult_browser_get_console \"/path/to/TestResults.xcresult\" \"MyTest/testMethod()\"\n\n# Get UI hierarchy at specific timestamp (AI-readable slim version)\nxcresult_get_ui_hierarchy \"/path/to/TestResults.xcresult\" \"MyTest/testMethod()\" 45.25\n\n# Get full UI hierarchy (with size warning)\nxcresult_get_ui_hierarchy \"/path/to/TestResults.xcresult\" \"MyTest/testMethod()\" 45.25 true\n\n# Get detailed properties of a specific UI element\nxcresult_get_ui_element \"/path/to/ui_hierarchy_full.json\" 15\n\n# Extract screenshot at failure point\nxcresult_get_screenshot \"/path/to/TestResults.xcresult\" \"MyTest/testMethod()\" 30.71\n```\n\n## Configuration\n\n### Logging Configuration\n\nXcodeMCP supports configurable logging to help with debugging and monitoring:\n\n#### Environment Variables\n\n- **`LOG_LEVEL`**: Controls logging verbosity (default: `INFO`)\n - `SILENT`: No logging output\n - `ERROR`: Only error messages\n - `WARN`: Warnings and errors\n - `INFO`: General operational information (recommended)\n - `DEBUG`: Detailed diagnostic information\n\n- **`XCODEMCP_LOG_FILE`**: Optional file path for logging\n - Logs are written to the specified file in addition to stderr\n - Parent directories are created automatically\n - Example: `/tmp/xcodemcp.log` or `~/Library/Logs/xcodemcp.log`\n\n- **`XCODEMCP_CONSOLE_LOGGING`**: Enable/disable console output (default: `true`)\n - Set to `false` to disable stderr logging (useful when using file logging only)\n\n#### Examples\n\n**Debug logging with file output:**\n```json\n{\n \"mcpServers\": {\n \"xcodemcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"xcodemcp@latest\"],\n \"env\": {\n \"LOG_LEVEL\": \"DEBUG\",\n \"XCODEMCP_LOG_FILE\": \"~/Library/Logs/xcodemcp.log\"\n }\n }\n }\n}\n```\n\n**Silent mode (no logging):**\n```json\n{\n \"mcpServers\": {\n \"xcodemcp\": {\n \"command\": \"npx\", \n \"args\": [\"-y\", \"xcodemcp@latest\"],\n \"env\": {\n \"LOG_LEVEL\": \"SILENT\"\n }\n }\n }\n}\n```\n\n**File-only logging:**\n```json\n{\n \"mcpServers\": {\n \"xcodemcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"xcodemcp@latest\"], \n \"env\": {\n \"LOG_LEVEL\": \"INFO\",\n \"XCODEMCP_LOG_FILE\": \"/tmp/xcodemcp.log\",\n \"XCODEMCP_CONSOLE_LOGGING\": \"false\"\n }\n }\n }\n}\n```\n\nAll logs are properly formatted with timestamps and log levels, and stderr output maintains compatibility with the MCP protocol.\n\n## Troubleshooting\n\n### XCLogParser Not Found\n\nIf you see a warning that XCLogParser is not found even though it's installed:\n\n1. **Verify installation:**\n ```bash\n which xclogparser\n xclogparser version\n ```\n\n2. **Common issues and solutions:**\n - **PATH issue**: If `which xclogparser` returns nothing, add the installation directory to your PATH:\n ```bash\n # For Homebrew on Intel Macs\n export PATH=\"/usr/local/bin:$PATH\"\n \n # For Homebrew on Apple Silicon Macs\n export PATH=\"/opt/homebrew/bin:$PATH\"\n ```\n \n - **Wrong command**: Older documentation may reference `xclogparser --version`, but the correct command is `xclogparser version` (without dashes)\n \n - **Permission issue**: Ensure xclogparser is executable:\n ```bash\n chmod +x $(which xclogparser)\n ```\n\n3. **Environment validation**: Run the health check to get detailed diagnostics:\n ```bash\n echo '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"xcode_health_check\", \"arguments\": {}}}' | npx xcodemcp\n ```\n\n**Note**: XcodeMCP can operate without XCLogParser, but build error parsing will be limited.\n\n## Example Output\n\n**Build with errors:**\n```\n❌ BUILD FAILED (2 errors)\n\nERRORS:\n • /path/HandsDownApp.swift:7:18: Expected 'func' keyword in instance method declaration\n • /path/MenuBarManager.swift:98:13: Invalid redeclaration of 'toggleItem'\n```\n\n**Health check:**\n```\n✅ All systems operational\n\n✅ OS: macOS environment detected\n✅ XCODE: Xcode found at /Applications/Xcode.app (version 16.4)\n✅ XCLOGPARSER: XCLogParser found (XCLogParser 0.2.41)\n✅ OSASCRIPT: JavaScript for Automation (JXA) is available\n✅ PERMISSIONS: Xcode automation permissions are working\n```\n",
"bytes": 16058,
"sha": "cf5165f7818414270490fbeb14183640c2412ad20d109573f1a3222e5fa83e34",
"repo_slug": "lapfelix/xcodemcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_lapfelix_xcodemcp_4e27df0f/readme"
}