Xcode MCP Server

对于 Apple 平台的开发者来说，Xcode 是承载一切代码和项目的“航母”。但当我们与 AI 编程助手协作时，一个根本性的鸿沟始终存在：AI 能看到代码，却无法直接操作 Xcode——不能读取项目文件、不能执行构建、不能在模拟器上运行测试。Xcode MCP Server 彻底弥合了这一鸿沟。它将 Xcode 生态的几乎全部能力——项目管理、文件操作、构建测试、CocoaPods 与 SPM 集成、模拟器控制——通过模型上下文协议（MCP）暴露给 AI 助手，让 Claude、Cursor 等 AI 成为真正的 Xcode 开发搭档。

项目基本信息

一、项目介绍

Xcode MCP Server 是一个功能庞大的 TypeScript 项目，它将 Xcode 开发环境中的几乎所有关键操作都封装成了 MCP 工具。其架构设计清晰，按功能领域将工具分为七大模块：

二、核心优势

Xcode 全工作流覆盖

从项目创建、依赖管理、代码编写，到构建测试、模拟器调试，直至 App Store 提交流程——Xcode MCP Server 覆盖了完整的 Apple 平台开发生命周期。AI 助手不再是只能“聊代码”的旁观者，而是能参与每一个实际操作环节的协作者。

智能路径管理与安全机制

服务器通过 PROJECTS_BASE_DIR 和 ALLOWED_PATHS 配置，严格限制所有文件操作的边界。这种设计既保证 AI 能够访问项目文件，又防止它意外触及系统敏感区域。所有输入参数使用 Zod 模式进行验证，外部进程执行也带有完善的错误处理。

开发友好的安装体验

项目提供了两套安装方案：

1. 自动化安装脚本（setup.sh）：一键完成环境验证、依赖安装、配置文件生成，甚至自动配置 Claude Desktop 集成。
2. 手动安装步骤：对于需要精细控制的开发者，从克隆仓库到构建项目到配置环境变量，每一步都有清晰指引。

MIT 开源协议

采用完全商业友好的 MIT 协议，适合个人和团队在任何项目中使用。

三、适用场景

AI 驱动的新项目搭建

用户：帮我创建一个名为“HealthTracker”的 iOS 应用，使用 SwiftUI，包含测试模板，然后添加 Alamofire 和 SwiftyJSON 作为依赖。

AI 依次调用 create_xcode_project、add_swift_package 等工具，完成从脚手架到依赖管理的全流程。

自动化构建与错误诊断

用户：构建一下当前项目，如果有错误，帮我分析并修复。

AI 调用 build_project 执行构建，获取错误输出，然后利用文本编辑能力直接在代码中修正问题。

模拟器测试与截图

用户：在 iPhone 16 模拟器上启动应用，等待 3 秒加载完成后截个图，然后把截图保存到桌面。

AI 调用 list_simulators 找到目标设备，launch_simulator 启动它，install_app 安装应用，take_screenshot 捕获画面，write_file 保存截图文件。

依赖管理与更新

用户：把项目中的 Alamofire 升级到 6.0 版本，然后更新所有 Pods。

AI 调用 add_swift_package（或 add_cocoapod）修改依赖版本，然后执行 update_pods 或 update_swift_packages 完成更新。

四、安装教程

环境要求

安装步骤

方式一：自动化安装（推荐）

# 克隆仓库
git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server

# 赋予脚本执行权限
chmod +x setup.sh

# 运行安装脚本
./setup.sh

脚本会自动完成环境验证、依赖安装、项目构建和配置文件生成。根据交互提示输入你的项目基础目录，选择是否启用调试日志，以及是否自动配置 Claude Desktop 集成。

方式二：手动安装

# 1. 克隆仓库
git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 创建配置文件
cp .env.example .env
# 编辑 .env 文件，设置你的项目基础目录
echo "PROJECTS_BASE_DIR=/Users/你的用户名/Projects" > .env

配置 Claude Desktop（或其他 MCP 客户端）

编辑 Claude Desktop 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/绝对路径/xcode-mcp-server/dist/index.js"]
    }
  }
}

注意：args 中的路径必须是指向 dist/index.js 的绝对路径。如果使用了自动化安装脚本，这部分会自动配置。

保存配置文件后，完全退出并重启 Claude Desktop。

启动服务器

# 生产模式启动
npm start

# 开发模式启动（自动重启）
npm run dev

五、使用示例

示例一：创建新项目

用户：帮我创建一个叫“TodoApp”的 iOS 应用，使用 Swift 语言，包含测试模板，组织名称为“MyCompany”。

AI 调用 create_xcode_project 工具，传入模板、语言、组织信息等参数。项目创建完成后，AI 会返回项目的路径和基本信息。

示例二：读取项目文件并修改

用户：读取 TodoApp/ContentView.swift 文件的内容，然后在 body 中添加一个“Hello World”文本视图。

AI 调用 read_file 获取文件内容，理解现有结构，然后调用 write_file 写入修改后的代码。

示例三：构建并处理错误

用户：构建 TodoApp 的 Debug 配置，如果有编译错误，帮我分析并修复。

AI 调用 build_project，传入 scheme 和配置。若构建失败，AI 解析错误输出，定位到问题文件和行号，再用文件操作工具修复代码，然后重新构建。

示例四：模拟器操作全流程

用户：在 iPhone 15 Pro 模拟器上启动 TodoApp，等待 5 秒截图，然后把截图保存到桌面。

AI 依次调用 list_simulators（找到目标模拟器）、launch_simulator、install_app、take_screenshot、write_file。

六、常见问题

问：安装后启动失败，提示“路径访问错误”？

答：这是安全机制在工作。请检查 .env 文件中的 PROJECTS_BASE_DIR 是否设置为你实际的项目目录。所有 AI 可访问的文件必须位于该目录或 ALLOWED_PATHS 指定的附加目录中。

问：CocoaPods 相关操作提示“找不到 CocoaPods”？

答：确保已经安装 CocoaPods：sudo gem install cocoapods。如果使用 rbenv 或 rvm 管理 Ruby，请确认 CocoaPods 在当前 Ruby 环境中可用。

问：模拟器列表为空，或者无法启动模拟器？

答：请确认：

1. Xcode 已经成功安装并至少运行过一次（首次运行会安装额外组件）。
2. 在 Xcode 中至少下载过一个模拟器版本的镜像（Xcode -> Settings -> Platforms）。

问：构建项目时提示“未找到 Xcode 命令行工具”？

答：在终端运行 xcode-select --install 安装命令行工具。如果已安装但仍有问题，运行 sudo xcode-select --reset 重置路径。

问：可以在多个项目中同时使用这个服务器吗？

答：服务器的 PROJECTS_BASE_DIR 指定了基础目录，AI 可以操作该目录下的所有 Xcode 项目。如果需要严格隔离不同项目，可以为每个项目运行独立的 MCP 服务器实例，并配置各自的 PROJECTS_BASE_DIR。

七、总结

Xcode MCP Server 是 Apple 平台开发者的“AI 超级助手”。它将 Xcode 从一个人工操作的独立 IDE，升级为了可以被 AI 理解和操控的开发环境。项目管理、文件编辑、构建调试、依赖管理、模拟器控制——所有这些操作现在都可以在 AI 对话中自然完成，开发者不再需要在 IDE 和 AI 助手之间频繁切换。

对于所有 macOS 上的 Apple 平台开发者来说，花半小时完成安装配置，你将获得一位能够真正上手操作 Xcode 的 AI 搭档。