XcodeMCP

与 Apple 官方 Xcode MCP 配合使用：Apple 现已提供官方 Xcode MCP 服务。XcodeMCP 可通过伴随模式（--sidekick-only）与其同时运行，提供项目管理和 XCResult 分析等互补工具。未来版本中，XcodeMCP 默认将切换为仅伴随模式。查看下方配置。

XcodeMCP

通过 JavaScript for Automation (JXA) 直接控制 Xcode 的 Model Context Protocol (MCP) 服务。既可作为 MCP 服务使用，也可作为独立 CLI 使用。

功能

• 通过 JavaScript for Automation 直接控制 Xcode（而非 xcodebuild CLI）
• 在 Xcode 中打开项目、构建、运行、测试和调试
• 使用 XCLogParser 解析构建日志并精确定位错误
• 提供全面的环境验证和健康检查
• 在缺少可选依赖项时支持优雅降级
• 全新：包含功能齐全的 CLI，功能与 MCP 服务 100% 一致

要求

• 安装了 Xcode 的 macOS
• Node.js 18+
• XCLogParser（推荐）：brew install xclogparser

用法

XcodeMCP 有两种使用方式：

1. MCP 服务：与 Claude Desktop、VS Code 或其他 MCP 客户端集成
2. CLI 工具：通过 xcodecontrol 从终端直接运行命令

快速安装

推荐安装 XCLogParser，但它是可选的：

brew install xclogparser

从 npm 安装

使用 npx 直接运行：

npx -y xcodemcp@latest

或进行全局安装：

npm install -g xcodemcp

MCP 配置

将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
      }
    }
  }
}

Claude Code CLI 设置

使用命令行将 XcodeMCP 添加到 Claude Code：

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
  }
}'

不使用 clean build folder 工具

使用命令行将 XcodeMCP 添加到 Claude Code：

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest", "--no-clean"],
  "env": {
  }
}'

为单项目工作流使用首选值

对于仅使用单个 xcodeproj 和 scheme 的项目，可以配置首选值，使工具参数变为可选：

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
    "XCODE_MCP_PREFERRED_SCHEME": "MyApp",
    "XCODE_MCP_PREFERRED_XCODEPROJ": "MyApp.xcodeproj"
  }
}'

配置首选值后：

• 工具参数将变为可选，而非必填
• 工具说明会显示默认值（例如，“默认为 MyApp.xcodeproj”）
• 仍可通过提供明确参数来覆盖默认值
• 在处理单个项目时可减少重复操作

故障排除

如果 Claude Code 中的 /mcp 显示 MCP 失败，请尝试在项目文件夹中手动运行，以查看输出内容：npx -y xcodemcp@latest

Sidekick 模式

将 XcodeMCP 与 Apple 官方 Xcode MCP 服务 一起使用时，启用 sidekick 模式，仅包含互补工具：

• 项目管理：打开/关闭项目、管理方案、查看工作区信息
• XCResult 分析：浏览测试结果、提取屏幕截图、检查 UI 层级结构

此模式会排除 Apple MCP 原生支持的构建/运行/测试/调试工具。

Claude Code CLI 设置（两个服务）

首先，在 Xcode > Settings > Intelligence > Model Context Protocol 中启用 Xcode Tools。

然后同时添加 Apple 的 Xcode MCP 和处于 sidekick 模式的 XcodeMCP：

# Add Apple's official Xcode MCP
claude mcp add --transport stdio xcode -- xcrun mcpbridge

# Add XcodeMCP in sidekick mode (project management + XCResult analysis)
claude mcp add-json xcodemcp '{"command": "npx", "args": ["-y", "xcodemcp@latest", "--sidekick-only"]}'

JSON 配置（两个服务）

{
  "mcpServers": {
    "xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"]
    },
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest", "--sidekick-only"]
    }
  }
}

未来方向：在未来版本中，XcodeMCP 将默认转为仅 sidekick 模式，专注于与 Apple 官方 Xcode MCP 互补的工具，而非重复其功能。

开发环境设置

本地开发：

git clone https://github.com/lapfelix/XcodeMCP.git
cd XcodeMCP
npm install

# Run in development mode (TypeScript)
npm run dev:ts

# Or build and run compiled version
npm run build
npm start

CLI 用法

XcodeMCP 提供功能强大的 CLI，与 MCP 服务的功能完全一致，可让你将任何工具作为一次性命令运行：

安装

全局安装以使用 CLI：

npm install -g xcodemcp

基本用法

# Show help and available tools
xcodecontrol --help

# Run a tool with flags  
xcodecontrol build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# Get help for a specific tool
xcodecontrol build --help

# Use JSON input instead of flags
xcodecontrol build --json-input '{"xcodeproj": "/path/to/Project.xcodeproj", "scheme": "MyScheme"}'

# Output results in JSON format
xcodecontrol --json health-check

路径解析

CLI 支持绝对路径和相对路径，使用起来更加方便：

# Absolute paths (traditional)
xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# Relative paths (NEW in v2.0.0)
xcodecontrol build --xcodeproj MyApp.xcodeproj --scheme MyApp
xcodecontrol build --xcodeproj ../OtherProject/OtherProject.xcodeproj --scheme OtherApp

# Works with file paths too
xcodecontrol open-file --filePath src/ViewController.swift --lineNumber 42

相对路径会从当前工作目录解析，因此在项目目录中工作时，CLI 会更便于使用。

详细程度控制

使用详细程度标志控制日志输出：

# Verbose mode (shows INFO and DEBUG logs)
xcodecontrol -v build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# Quiet mode (only errors)
xcodecontrol -q test --xcodeproj /path/to/Project.xcodeproj

# Default mode (warnings and errors only)
xcodecontrol run --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

快速示例

# Check system health
xcodecontrol health-check

# Build a project
xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# Run the app
xcodecontrol run --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# Run tests
xcodecontrol test --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

# Clean build directory
xcodecontrol clean --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj

# Browse XCResult files
xcodecontrol xcresult-browse --xcresult-path /path/to/result.xcresult

# Get UI hierarchy from test failure
xcodecontrol xcresult-get-ui-hierarchy --xcresult-path /path/to/result.xcresult --test-id "MyTest/testMethod()" --timestamp 30.5

工具名称映射

CLI 命令使用 kebab-case，而不是下划线：

• xcode_build → build
• xcode_test → test
• xcode_build_and_run → build-and-run
• xcode_health_check → health-check
• xcresult_browse → xcresult-browse
• find_xcresults → find-xcresults

可用工具

项目管理：

• xcode_open_project - 打开项目和工作区
• xcode_get_workspace_info - 获取工作区状态和详细信息
• xcode_get_projects - 列出工作区中的项目
• xcode_open_file - 打开文件，可选指定行号

构建操作：

• xcode_build - 构建并详细解析错误
• xcode_clean - 清理构建产物
• xcode_test - 运行测试，可选传入参数
• xcode_build_and_run - 构建并运行当前活动方案
• xcode_debug - 启动调试会话
• xcode_stop - 停止当前操作

配置：

• xcode_get_schemes - 列出可用方案
• xcode_set_active_scheme - 切换活动方案
• xcode_get_run_destinations - 列出模拟器和设备

XCResult 分析：

• xcresult_browse - 浏览测试结果并分析失败
• xcresult_browser_get_console - 获取特定测试的控制台输出
• xcresult_summary - 快速概览测试结果
• xcresult_get_screenshot - 从测试失败中提取屏幕截图
• xcresult_get_ui_hierarchy - 获取 AI 可读的 JSON 格式 UI 层级结构，并选择时间戳
• xcresult_get_ui_element - 按索引获取特定 UI 元素的详细属性
• xcresult_list_attachments - 列出某个测试的所有附件
• xcresult_export_attachment - 从测试结果中导出特定附件

诊断：

• xcode_health_check - 环境验证和故障排除

XCResult 分析功能

XcodeMCP 提供全面的工具来分析 Xcode 测试结果（.xcresult 文件），让调试测试失败和提取有价值的信息变得轻松：

测试结果分析

• 浏览结果：浏览测试层级结构、查看通过/失败状态并检查详细测试信息
• 控制台日志：提取控制台输出和测试活动，并提供精确时间戳以便调试
• 快速摘要：获取概览统计信息，包括通过率、失败次数和持续时间

可视化调试

• 截图提取：通过从视频附件中使用 ffmpeg 提取帧，从测试失败记录中提取 PNG 截图
• 时间戳精度：指定精确时间戳，以捕获测试执行特定时刻的 UI 状态

UI 层级分析

• 便于 AI 阅读的格式：将 UI 层级提取为压缩 JSON，并使用单字母属性（t=类型，l=标签，f=框架，c=子项，j=索引）
• 时间戳选择：自动查找与指定时间戳最接近的 UI 层级捕获记录
• 元素深入分析：使用索引引用获取任意 UI 元素的完整详细信息，包括无障碍属性和框架信息
• 大小优化：与完整层级数据相比，体积减少 75% 以上，同时保留所有关键信息

附件管理

• 完整清单：列出任意测试的所有附件（截图、视频、调试描述、UI 层级）
• 选择性导出：按索引或类型导出特定附件
• 智能检测：自动识别并分类不同类型的附件

使用示例

# Browse test results
xcresult_browse "/path/to/TestResults.xcresult"

# Get console output to find failure timestamps
xcresult_browser_get_console "/path/to/TestResults.xcresult" "MyTest/testMethod()"

# Get UI hierarchy at specific timestamp (AI-readable slim version)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25

# Get full UI hierarchy (with size warning)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25 true

# Get detailed properties of a specific UI element
xcresult_get_ui_element "/path/to/ui_hierarchy_full.json" 15

# Extract screenshot at failure point
xcresult_get_screenshot "/path/to/TestResults.xcresult" "MyTest/testMethod()" 30.71

配置

日志配置

XcodeMCP 支持可配置的日志记录，便于调试和监控：

环境变量

• LOG_LEVEL：控制日志详细程度（默认：INFO）

  • SILENT：不输出日志
  • ERROR：仅输出错误消息
  • WARN：输出警告和错误
  • INFO：常规运行信息（推荐）
  • DEBUG：详细诊断信息

• XCODEMCP_LOG_FILE：可选的日志文件路径

  • 除 stderr 外，还会将日志写入指定文件
  • 自动创建父目录
  • 示例：/tmp/xcodemcp.log 或 ~/Library/Logs/xcodemcp.log

• XCODEMCP_CONSOLE_LOGGING：启用/禁用控制台输出（默认：true）

  • 设置为 false 可禁用 stderr 日志（仅使用文件日志时很有用）

示例

启用调试日志并输出到文件：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "XCODEMCP_LOG_FILE": "~/Library/Logs/xcodemcp.log"
      }
    }
  }
}

静默模式（不记录日志）：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx", 
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "SILENT"
      }
    }
  }
}

仅记录到文件：

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"], 
      "env": {
        "LOG_LEVEL": "INFO",
        "XCODEMCP_LOG_FILE": "/tmp/xcodemcp.log",
        "XCODEMCP_CONSOLE_LOGGING": "false"
      }
    }
  }
}

所有日志都会正确格式化，并包含时间戳和日志级别；stderr 输出也与 MCP 协议保持兼容。

故障排除

未找到 XCLogParser

如果看到未找到 XCLogParser 的警告，但实际上已安装：

1. 验证安装：

   which xclogparser
   xclogparser version
   

2. 常见问题及解决方案：

   • PATH 问题：如果 which xclogparser 没有返回结果，请将安装目录添加到 PATH：

     # Intel Mac 上使用 Homebrew
     export PATH="/usr/local/bin:$PATH"
     
     # Apple Silicon Mac 上使用 Homebrew
     export PATH="/opt/homebrew/bin:$PATH"
     

   • 命令错误：较旧的文档可能会提到 xclogparser --version，但正确的命令是 xclogparser version（不带连字符）

   • 权限问题：确保 xclogparser 可执行：

     chmod +x $(which xclogparser)
     

3. 环境验证：运行健康检查以获取详细诊断信息：

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "xcode_health_check", "arguments": {}}}' | npx xcodemcp
   

注意：XcodeMCP 无需 XCLogParser 也能运行，但解析构建错误的能力会受到限制。

输出示例

存在错误的构建：

❌ BUILD FAILED (2 errors)

ERRORS:
  • /path/HandsDownApp.swift:7:18: Expected 'func' keyword in instance method declaration
  • /path/MenuBarManager.swift:98:13: Invalid redeclaration of 'toggleItem'

健康检查：

✅ All systems operational

✅ OS: macOS environment detected
✅ XCODE: Xcode found at /Applications/Xcode.app (version 16.4)
✅ XCLOGPARSER: XCLogParser found (XCLogParser 0.2.41)
✅ OSASCRIPT: JavaScript for Automation (JXA) is available
✅ PERMISSIONS: Xcode automation permissions are working