{"id":28557552,"url":"https://github.com/lapfelix/xcodemcp","last_synced_at":"2025-10-10T03:34:55.556Z","repository":{"id":297321958,"uuid":"996409724","full_name":"lapfelix/XcodeMCP","owner":"lapfelix","description":"MCP server for Xcode that wraps its AppleScript interface \u0026 uses XCLogParser to return clear build results","archived":false,"fork":false,"pushed_at":"2025-09-18T03:22:36.000Z","size":690,"stargazers_count":41,"open_issues_count":4,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-19T14:41:40.429Z","etag":null,"topics":["agentic-ai","applescript","claude-code","mcp","xcode"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lapfelix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-04T23:06:28.000Z","updated_at":"2025-09-18T03:22:40.000Z","dependencies_parsed_at":"2025-06-05T04:21:04.137Z","dependency_job_id":"736dc29e-c79d-48f1-9c1c-1d5483657856","html_url":"https://github.com/lapfelix/XcodeMCP","commit_stats":null,"previous_names":["lapfelix/xcodemcp"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/lapfelix/XcodeMCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lapfelix%2FXcodeMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lapfelix%2FXcodeMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lapfelix%2FXcodeMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lapfelix%2FXcodeMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lapfelix","download_url":"https://codeload.github.com/lapfelix/XcodeMCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lapfelix%2FXcodeMCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002623,"owners_count":26083425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","applescript","claude-code","mcp","xcode"],"created_at":"2025-06-10T07:38:35.689Z","updated_at":"2025-10-10T03:34:55.550Z","avatar_url":"https://github.com/lapfelix.png","language":"TypeScript","funding_links":[],"categories":["Developer Tools"],"sub_categories":["How to Submit"],"readme":"# XcodeMCP\n\n[![npm version](https://img.shields.io/npm/v/xcodemcp.svg)](https://www.npmjs.com/package/xcodemcp)\n[![Test Status](https://github.com/lapfelix/XcodeMCP/actions/workflows/test.yml/badge.svg)](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[\u003cimg src=\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square\u0026label=Install%20Server\u0026color=0098FF\" alt=\"Install in VS Code\"\u003e](https://insiders.vscode.dev/redirect/mcp/install?name=xcodemcp\u0026config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22xcodemcp%40latest%22%5D%7D)\n[\u003cimg alt=\"Install in VS Code Insiders\" src=\"https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square\u0026label=Install%20Server\u0026color=24bfa5\"\u003e](https://insiders.vscode.dev/redirect/mcp/install?name=xcodemcp\u0026config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22xcodemcp%40latest%22%5D%7D\u0026quality=insiders)\n[\u003cimg src=\"https://cursor.com/deeplink/mcp-install-dark.svg\" height=20 alt=\"Install MCP Server\"\u003e](https://cursor.com/install-mcp?name=XcodeMCP\u0026config=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### 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flapfelix%2Fxcodemcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flapfelix%2Fxcodemcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flapfelix%2Fxcodemcp/lists"}