Xcode MCP

与苹果官方Xcode MCP一起使用：苹果现在提供 官方Xcode MCP服务器.XcodeMCP可以与它一起运行 侧踢模式 (--sidekick-only)，提供项目管理和XCResult分析等补充工具。在未来的版本中，XcodeMCP将默认转换为仅支持助手模式。 请参阅下面的配置.

Xcodemcp

](https://www.npmjs.com/package/xcodemcp) 

模型上下文协议（MCP）服务器，通过JavaScript for Automation（JXA）直接控制Xcode。可作为MCP服务器和独立CLI使用。

它做什么

• 通过JavaScript直接控制Xcode以实现自动化（不是xcodebuild CLI）
• 从Xcode中打开项目、构建、运行、测试和调试
• 使用以下命令解析具有精确错误位置的构建日志 XCLogParser
• 提供全面的环境验证和健康检查
• 当缺少可选依赖项时，支持优雅降级
• 新：包括一个功能齐全的CLI，具有100%MCP服务器功能奇偶校验

需求

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

用法

XcodeMCP可以通过两种方式使用：

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

快速安装

[](https://cursor.com/install-mcp?name=XcodeMCP&config=eyJjb21tYW5kIjoibnB4IHhjb2RlbWNwQGxhdGVzdCIsImVudiI6e319)

建议使用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代码CLI设置

要使用命令行将XcodeMCP添加到Claude代码中，请执行以下操作：

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

没有清理构建文件夹工具

要使用命令行将XcodeMCP添加到Claude代码中，请执行以下操作：

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

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

对于使用单个xcodeproj和方案的项目，您可以配置首选值，使工具参数可选：

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”）
• 您仍然可以通过提供显式参数来覆盖默认值
• 在处理单个项目时减少重复

故障排除

如果 /mcp 如果Claude Code指示MCP失败，请尝试从项目文件夹手动运行它，以查看输出结果： npx -y xcodemcp@latest

侧踢模式

与XcodeMCP一起使用时 苹果官方Xcode MCP服务器，启用助手模式仅包括补充工具：

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

这不包括苹果MCP本机处理的构建/运行/测试/调试工具。

Claude Code CLI安装程序（两台服务器）

首先，在Xcode>设置>智能>模型上下文协议中启用Xcode工具。

然后在侧踢模式下添加苹果的Xcode MCP和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将默认转换为仅支持助手模式，专注于补充苹果官方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服务器100%的功能对等性，允许您一次性运行任何工具：

安装

全局安装以使用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命令使用烤肉串大小写而不是下划线：

• 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 -列出模拟器和设备

XC结果分析：

• xcresult_browse -浏览测试结果并分析故障
• xcresult_browser_get_console -获取特定测试的控制台输出
• xcresult_summary -测试结果快速概述
• xcresult_get_screenshot -从测试失败中提取屏幕截图
• xcresult_get_ui_hierarchy -使用时间戳选择将UI层次结构获取为AI可读的JSON
• 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

1. 常见问题和解决方案：

- PATH问题：如果 which xclogparser 不返回任何内容，请将安装目录添加到PATH中：

     # For Homebrew on Intel Macs
     export PATH="/usr/local/bin:$PATH"

     # For Homebrew on Apple Silicon Macs
     export PATH="/opt/homebrew/bin:$PATH"

- 错误的命令：可以参考旧文件 xclogparser --version，但正确的命令是 xclogparser version （无破折号）

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

     chmod +x $(which xclogparser)

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

   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