Xcode MCP Server

一个提供全面 Xcode 集成的 MCP（模型上下文协议）服务器，用于 AI 助手。该服务器使 AI 代理能够与 Xcode 项目交互、管理 iOS 模拟器并执行各种 Xcode 相关任务，具有增强的错误处理和多项目类型支持。

功能

项目管理

设置活动项目并获取详细的项目信息
从模板创建新的 Xcode 项目（iOS、macOS、watchOS、tvOS）
按目标和分组将文件添加到 Xcode 项目中
解析工作区文档以查找相关项目
列出项目和工作区中的可用方案

文件操作

支持不同编码的文件读写
处理使用 base64 编码/解码的二进制文件
使用模式和正则表达式在文件中搜索文本内容
检查文件是否存在并获取文件元数据
自动创建目录结构

构建与测试

使用可自定义选项构建项目
运行测试并报告详细的失败信息
分析代码以查找潜在问题
清理构建目录
归档项目以进行分发

CocoaPods 集成

在项目中初始化 CocoaPods
安装和更新 pod
添加和移除 pod 依赖
执行任意 pod 命令

Swift Package Manager

初始化新的 Swift 包
添加和移除具有各种版本要求的包依赖
更新包并解析依赖
使用 DocC 为 Swift 包生成文档
运行 Swift 包的测试和构建

iOS 模拟器工具

列出可用模拟器并显示详细信息
启动和关闭模拟器
在模拟器上安装和启动应用
拍摄屏幕截图和录制视频
管理模拟器设置和状态

Xcode 实用工具

通过 xcrun 执行 Xcode 命令
编译资产目录
从源图像生成应用图标集
追踪应用性能
导出和验证用于 App Store 提交的归档文件
在不同的 Xcode 版本之间切换

安装

前置条件

安装了 Xcode 14.0 或更高版本的 macOS
Node.js 16 或更高版本
npm 或 yarn
Swift 5.5+（用于 Swift Package Manager 功能）
CocoaPods（可选，用于 CocoaPods 集成）

设置

选项 1：自动设置（推荐）

使用随附的设置脚本自动执行安装和配置过程：

# 使脚本可执行
chmod +x setup.sh

# 运行设置脚本
./setup.sh

设置脚本执行的操作：

环境验证：
- 检查是否在 macOS 上运行
- 验证 Xcode 是否已安装且可访问
- 确认 Node.js (v16+) 和 npm 是否可用
- 检查 Ruby 安装情况
- 验证 CocoaPods 安装情况（如果缺失则提供安装选项）
依赖安装：
- 运行 npm install 安装所有必需的 Node.js 包
- 执行 npm run build 编译 TypeScript 代码
配置设置：
- 如果不存在，则创建 .env 文件
- 提示输入项目基本目录
- 询问是否要启用调试日志记录
- 保存您的配置偏好
Claude Desktop 集成（可选）：
- 提供配置服务器以供 Claude Desktop 使用的选项
- 创建或更新 Claude Desktop 配置文件
- 设置启动服务器所需的正确命令和参数

何时使用设置脚本：

首次安装以确保所有前置条件都已满足
当您需要交互式提示的引导配置时
如果您想快速设置 Claude Desktop 集成
验证您的环境是否包含所有必要组件

脚本将引导您完成配置过程，提供清晰的提示和有用的反馈。

选项 2：手动设置

何时使用手动设置：

您希望显式控制每个安装步骤
您拥有自定义环境或非标准配置
您在 CI/CD 管道或自动化环境中设置
您想自定义安装过程的特定方面
您是熟悉 Node.js 项目的经验丰富的开发者

按照以下步骤进行手动安装：

克隆存储库：

git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server

验证前置条件（这些必须已安装）：
- Xcode 和 Xcode 命令行工具
- Node.js v16 或更高版本
- npm
- Ruby（用于 CocoaPods 支持）
- CocoaPods（可选，用于 pod 相关功能）
安装依赖：
```
npm install
```
构建项目：
```
npm run build
```

创建配置文件：

# 选项 A：从示例配置开始
cp .env.example .env

# 选项 B：创建最小配置
echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
echo "DEBUG=false" >> .env

编辑 .env 文件以设置您的首选配置。

对于 Claude Desktop 集成（可选）：
- 编辑或创建 ~/Library/Application Support/Claude/claude_desktop_config.json
- 添加以下配置（根据需要调整路径）：
```
{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/path/to/xcode-mcp-server/dist/index.js"]
    }
  }
}
```

设置故障排除

常见设置问题：

构建错误：
- 确保您使用的是正确的 Node.js 版本 (v16+)
- 尝试删除 node_modules 并再次运行 npm install
- 使用 npx tsc --noEmit 检查 TypeScript 错误
- 确保代码中的所有导入都已正确解析
缺失依赖：
- 如果您看到关于缺失模块的错误，请再次运行 npm install
- 对于原生依赖，您可能需要安装 Xcode 命令行工具：xcode-select --install
权限问题：
- 确保您对安装目录具有写入权限
- 对于 CocoaPods 安装，您可能需要使用 sudo gem install cocoapods
配置问题：
- 验证您的 .env 文件是否具有正确的格式和有效路径
- 确保 PROJECTS_BASE_DIR 指向一个现有目录
- 检查路径是否包含需要转义的特殊字符
Claude Desktop 集成：
- 确保Claude配置中的路径指向 index.js 的正确位置
- 在进行配置更改后重启 Claude Desktop
- 在尝试使用 Claude 之前检查服务器是否正在运行

使用

启动服务器

npm start

对于开发模式（自动重启）：

npm run dev

配置选项

您可以通过以下两种方式配置服务器：

.env 文件中的环境变量：

PROJECTS_BASE_DIR=/path/to/your/projects
DEBUG=true
ALLOWED_PATHS=/path/to/additional/allowed/directory
PORT=8080

命令行参数：

npm start -- --projects-dir=/path/to/your/projects --port=8080

关键配置参数

PROJECTS_BASE_DIR / --projects-dir：项目基本目录（必需）
ALLOWED_PATHS / --allowed-paths：允许访问的附加目录（逗号分隔）
PORT / --port：服务器运行的端口（默认：3000）
DEBUG / --debug：启用调试日志记录（默认：false）
LOG_LEVEL / --log-level：设置日志级别（默认：info）

连接到 AI 助手

服务器实现了模型上下文协议（MCP），使其与支持此协议的各种 AI 助手兼容。要连接：

启动 Xcode MCP 服务器
配置您的 AI 助手使用服务器 URL（通常是 http://localhost:3000）
现在 AI 助手将可以访问服务器提供的所有 Xcode 工具

工具文档

有关所有可用工具及其用法的全面概述，请参阅工具概述。

有关详细的用法示例和最佳实践，请参阅用户指南。

常见工作流

设置新项目

// 创建一个新的 iOS 应用项目
await tools.create_xcode_project({
  name: "MyAwesomeApp",
  template: "ios-app",
  outputDirectory: "~/Projects",
  organizationName: "My Organization",
  organizationIdentifier: "com.myorganization",
  language: "swift",
  includeTests: true,
  setAsActive: true
});

// 添加一个 Swift Package 依赖
await tools.add_swift_package({
  url: "https://github.com/Alamofire/Alamofire.git",
  version: "from: 5.0.0"
});

文件操作

// 使用特定编码读取文件
const fileContent = await tools.read_file({
  filePath: "MyAwesomeApp/AppDelegate.swift",
  encoding: "utf-8"
});

// 写入文件
await tools.write_file({
  path: "MyAwesomeApp/NewFile.swift",
  content: "import Foundation\n\nclass NewClass {}\n",
  createIfMissing: true
});

// 在文件中搜索文本
const searchResults = await tools.search_in_files({
  directory: "MyAwesomeApp",
  pattern: "*.swift",
  searchText: "class",
  isRegex: false
});

构建和测试

// 构建项目
await tools.build_project({
  scheme: "MyAwesomeApp",
  configuration: "Debug"
});

// 运行测试
await tools.test_project({
  scheme: "MyAwesomeApp",
  testPlan: "MyAwesomeAppTests"
});

项目结构

xcode-mcp-server/
├── src/
│   ├── index.ts                 # 入口点
│   ├── server.ts                # MCP 服务器实现
│   ├── types/                   # 类型定义
│   │   └── index.ts             # 核心类型定义
│   ├── utils/                   # 工具函数
│   │   ├── errors.js            # 错误处理类
│   │   ├── pathManager.ts       # 路径验证和管理
│   │   ├── project.js           # 项目工具
│   │   └── simulator.js         # 模拟器工具
│   └── tools/                   # 工具实现
│       ├── project/             # 项目管理工具
│       │   └── index.ts         # 项目创建、检测、文件添加
│       ├── file/                # 文件操作工具
│       │   └── index.ts         # 文件读取、写入、搜索
│       ├── build/               # 构建和测试工具
│       │   └── index.ts         # 构建、测试、分析
│       ├── cocoapods/           # CocoaPods 集成
│       │   └── index.ts         # Pod 安装和管理
│       ├── spm/                 # Swift Package Manager 工具
│       │   └── index.ts         # 包管理和文档生成
│       ├── simulator/           # iOS 模拟器工具
│       │   └── index.ts         # 模拟器控制和交互
│       └── xcode/               # Xcode 实用工具
│           └── index.ts         # Xcode 版本管理、资产工具
├── docs/                        # 文档
│   ├── tools-overview.md        # 全面工具文档
│   └── user-guide.md            # 用法示例和最佳实践
├── tests/                       # 测试
└── dist/                        # 编译代码（生成）

工作原理

Xcode MCP 服务器使用模型上下文协议（MCP）为 AI 模型提供标准化的 Xcode 项目交互接口。服务器架构设计包含几个关键组件：

核心组件

服务器实现：处理工具注册和请求处理的主 MCP 服务器。
路径管理：通过验证所有路径是否在允许的目录中来确保安全的文件访问。
项目管理：检测、加载和管理不同类型的 Xcode 项目：
- 标准 Xcode 项目 (.xcodeproj)
- Xcode 工作区 (.xcworkspace)
- Swift Package Manager 项目 (Package.swift)
目录状态：维护活动目录上下文以解析相对路径。
工具注册：将工具组织成逻辑类别以执行不同的 Xcode 操作。

请求流程

AI 助手向 MCP 服务器发送工具执行请求。
服务器验证请求参数和权限。
调用相应的工具处理程序并传递验证后的参数。
工具执行请求的操作，通常使用原生 Xcode 命令。
格式化结果并返回给 AI 助手。
综合错误处理提供有意义的反馈以帮助故障排除。

安全功能

路径验证：所有文件操作都限制在允许的目录内。
错误处理：提供详细的错误消息以帮助诊断问题。
参数验证：使用 Zod 模式验证输入参数。
进程管理：安全执行外部进程并具有适当的错误处理。

项目类型支持

服务器智能地处理不同类型的项目：

标准项目：直接操作 .xcodeproj
工作区：管理工作区中的多个项目
SPM 项目：处理 Swift Package Manager 特定操作

这种架构使 AI 助手能够无缝地与任何类型的 Xcode 项目协同工作，同时保持安全性并提供详细的反馈。

贡献

欢迎贡献！请随时提交 Pull Request。

分叉存储库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

开发指南

遵循现有的代码风格和组织结构
添加全面的错误处理和具体的错误消息
为新功能编写测试
更新文档以反映您的更改
确保与不同类型的项目（标准、工作区、SPM）兼容

添加新工具

要向服务器添加新工具：

在 src/tools/ 目录中确定适当的类别
使用现有的模式并使用 Zod 模式验证实现工具
在类别的 index.ts 文件中注册工具
添加具有具体错误消息的错误处理
在适当的文档文件中记录工具

故障排除

常见问题

路径访问错误：确保您尝试访问的路径在允许的目录内
构建失败：检查 Xcode 命令行工具是否已安装并更新
工具未找到：验证工具名称是否正确并已正确注册
参数验证错误：检查工具文档中参数的类型和需求

调试

启动服务器以启用调试日志记录：npm start -- --debug
检查控制台输出以获取详细的错误消息
检查服务器日志以获取请求和响应的详细信息
对于特定工具的问题，尝试在终端直接运行等效的 Xcode 命令

许可证

本项目根据 MIT 许可证授权 - 详细内容请参阅 LICENSE 文件。

致谢

感谢模型上下文协议团队提供的 MCP SDK
使用 TypeScript 和 Node.js 构建
使用 Xcode 命令行工具和 Swift Package Manager
特别感谢所有帮助改进服务器功能性和鲁棒性的贡献者

r-huijts/xcode-mcp-server

星标增长

证据时间轴

Xcode MCP Server

功能

项目管理

文件操作

构建与测试

CocoaPods 集成

Swift Package Manager

iOS 模拟器工具

Xcode 实用工具

安装

前置条件

设置

选项 1：自动设置（推荐）

选项 2：手动设置

设置故障排除

使用

启动服务器

配置选项

关键配置参数

连接到 AI 助手

工具文档

常见工作流

设置新项目

文件操作

构建和测试

项目结构

工作原理

核心组件

请求流程

安全功能

项目类型支持

贡献

开发指南

添加新工具

故障排除

常见问题

调试

许可证

致谢