Xcodebuildmcp

🚀 XcodeBuildMCP：集成AI助手與Xcode的MCP服務器

XcodeBuildMCP是一個模型上下文協議（MCP）服務器，它提供與Xcode相關的工具，可集成AI助手和其他MCP客戶端，助力開發者更高效地進行Xcode項目開發。

🚀 快速開始

項目概述

本項目實現了一個MCP服務器，將Xcode操作作為工具暴露出來，AI代理可通過MCP協議調用這些工具。它通過標準化接口實現與Xcode項目的編程式交互，為代理驅動的開發工作流程進行了優化。

使用Cursor在iOS模擬器上構建、安裝和啟動應用程序，並在運行時捕獲日誌。

項目存在的意義

XcodeBuild MCP工具的主要目的是簡化和標準化AI代理與Xcode項目之間的交互。通過為常見的Xcode操作提供專用工具，它消除了對手動或可能錯誤的命令行調用的依賴。

這確保了可靠且高效的開發過程，使代理能夠無縫利用Xcode的功能，同時降低配置錯誤的風險。

至關重要的是，這個MCP使AI代理能夠通過構建項目、檢查錯誤並自主迭代來獨立驗證代碼更改。與Sweetpad等用戶驅動的工具不同，XcodeBuild MCP使代理能夠有效地自動化這些工作流程。

前提條件

• macOS 14.5 或更高版本
• Xcode 16.x 或更高版本
• Node 18.x 或更高版本
• AXe 1.0.0 或更高版本（可選，UI自動化需要）

UI自動化

若要使用UI自動化功能（點擊、滑動、輸入等），你需要安裝AXe：

brew tap cameroncooke/axe
brew install axe

有關AXe和其他安裝方法的更多信息，請參閱 AXe倉庫。

配置MCP客戶端

快速安裝

你可以使用以下鏈接進行快速安裝：

• 

手動安裝

通過修改客戶端應用程序的MCP配置，將你的MCP客戶端（Windsurf、Cursor、Claude Desktop、Claude Code等）配置為使用XcodeBuildMCP服務器。

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ]
    }
  }
}

使用mise的替代安裝方法

你也可以使用mise來安裝XcodeBuildMCP，而無需單獨安裝Node.js：

# macOS (Homebrew)
brew install mise

# 其他安裝方法
# 請參閱 https://mise.jdx.dev/getting-started.html

然後將你的MCP客戶端配置為使用mise安裝XcodeBuildMCP：

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "mise",
      "args": [
        "x",
        "npm:xcodebuildmcp@1.7.0",
        "--",
        "xcodebuildmcp"
      ]
    }
  }
}

⚠️ 重要提示 使用mise時，避免使用@latest標籤，因為mise會緩存軟件包，可能不會自動更新到最新版本，建議使用明確的版本號。

⚠️ 重要提示 請注意，XcodeBuildMCP會請求xcodebuild跳過宏驗證，這是為了避免在構建使用Swift宏的項目時出錯。

✨ 主要特性

Xcode項目管理

• 項目發現：發現Xcode項目和工作區
• 構建操作：針對macOS、iOS模擬器和iOS設備目標的特定平臺構建工具
• 項目信息：列出Xcode項目和工作區的方案並顯示構建設置的工具
• 清理操作：使用xcodebuild的原生清理操作清理構建產品
• 增量構建支持：使用增量構建支持實現閃電般快速的構建（實驗性，需要手動啟用）
• 項目搭建：使用現代模板創建新的iOS和macOS項目，具備工作區 + SPM包架構，可自定義捆綁標識符、部署目標和設備系列

Swift包管理器

• 包構建：使用配置和架構選項構建Swift包
• 測試運行：執行Swift包測試套件，支持過濾和並行執行
• 可執行文件運行：執行包二進制文件，支持超時處理和後臺執行
• 進程管理：列出並停止使用Swift包工具啟動的長時間運行的可執行文件
• 工件清理：刪除構建工件和派生數據以進行全新構建

模擬器管理

• 模擬器控制：列出、啟動和打開iOS模擬器
• 應用部署：在iOS模擬器上安裝和啟動應用程序
• 日誌捕獲：從模擬器捕獲運行時日誌
• UI自動化：與模擬器UI元素進行交互（測試版）
• 屏幕截圖：從模擬器捕獲屏幕截圖（測試版）

應用實用工具

• 捆綁ID提取：從iOS和macOS應用程序包中提取捆綁標識符
• 應用啟動：在模擬器和macOS上啟動已構建的應用程序

📦 安裝指南

增量構建支持

XcodeBuildMCP包含對增量構建的實驗性支持。此功能默認禁用，可通過將INCREMENTAL_BUILDS_ENABLED環境變量設置為true來啟用：

啟用增量構建的示例MCP客戶端配置：

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "INCREMENTAL_BUILDS_ENABLED": "true"
      }        
    }
  }
}

⚠️ 重要提示 請注意，增量構建支持目前處於高度實驗階段，實際效果可能會有所不同。如果你遇到任何問題，請向 問題跟蹤器 報告。

🔧 技術細節

故障排除

診斷工具

診斷工具是一個獨立的實用程序，用於檢查你的系統配置並報告XcodeBuildMCP所需的所有依賴項的狀態。在報告問題時，它特別有用。

使用npx

# 使用npx運行診斷工具
npx xcodebuildmcp@1.7.0 xcodebuildmcp-diagnostic

使用mise

# 使用mise運行診斷工具
mise x npm:xcodebuildmcp@1.7.0 -- xcodebuildmcp-diagnostic

診斷工具將輸出以下方面的全面信息：

• 系統和Node.js環境
• Xcode安裝和配置
• 所需的依賴項（xcodebuild、AXe等）
• 影響XcodeBuildMCP的環境變量
• 功能可用性狀態

在GitHub上報告問題時，請包含診斷工具的完整輸出，以幫助進行故障排除。

MCP服務器日誌

訪問MCP服務器的日誌消息有助於識別問題。日誌由客戶端應用程序捕獲，例如在Cursor中：

find ~/Library/Application\ Support/Cursor/logs -name "Cursor MCP.log" -exec zip -r matching_logs.zip {} +

如果你的MCP客戶端沒有日誌文件，你可以使用MCP檢查器工具直接運行服務器，有關如何操作的更多信息，請參閱 調試。運行MCP工具後，所有日誌消息將打印到其錯誤面板，這有助於診斷問題。

隱私

本項目使用 Sentry 進行錯誤監控和診斷。Sentry幫助我們跟蹤問題、崩潰和意外錯誤，以提高XcodeBuildMCP的可靠性和穩定性。

發送到Sentry的內容

• 默認情況下，僅將錯誤級別的日誌和診斷信息發送到Sentry。
• 錯誤日誌可能包括錯誤消息、堆棧跟蹤，以及（在某些情況下）文件路徑或項目名稱等詳細信息。你可以查看此存儲庫中的源代碼，瞭解具體記錄的內容。

退出Sentry

如果你不想將錯誤日誌發送到Sentry，可以通過將環境變量SENTRY_DISABLED=true來退出。

退出Sentry的示例MCP客戶端配置：

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "SENTRY_DISABLED": "true"
      }        
    }
  }
}

選擇性工具註冊

默認情況下，所有工具均已啟用，但對於某些客戶端，僅啟用特定工具以減少發送到客戶端的上下文量可能會更有用。你可以通過在客戶端的MCP配置中設置特定的環境變量來實現這一點。

啟用一個或多個工具或工具組後，所有其他工具將被禁用。例如，若要僅啟用與模擬器相關的工具，可以將環境變量設置為XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW=true，這樣將僅暴露用於在模擬器上構建、運行和調試的工具。

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "npx",
      "args": [
        "-y",
        "xcodebuildmcp@latest"
      ],
      "env": {
        "XCODEBUILDMCP_GROUP_IOS_SIMULATOR_WORKFLOW": "true"
      }        
    }
  }
}

你可以在 TOOL_OPTIONS.md 文件中找到可用工具的列表以及如何啟用它們的詳細說明。

📚 詳細文檔

演示

在Cursor中自動修復構建錯誤

利用新的UI自動化和屏幕捕獲功能

在Claude Desktop中構建和運行iOS應用程序

https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086

貢獻

歡迎貢獻代碼！以下是你可以幫助改進XcodeBuildMCP的方法。 有關如何配置本地環境併為項目做出貢獻的更多信息，請參閱我們的 CONTRIBUTING 文檔。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

MCP服務器驗證

Glama.ai

MseeP.a