Skip to main content
Glama
enesjakozh

Xcode MCP Server

by r-huijts
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Local
MIT License
13
330

Xcode MCP 服务器

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

特征

项目管理

  • 设置活跃项目并获取详细项目信息

  • 从模板创建新的 Xcode 项目（iOS、macOS、watchOS、tvOS）

  • 使用目标和组规范将文件添加到 Xcode 项目

  • 解析工作区文档以查找相关项目

  • 列出项目和工作区中可用的方案

文件操作

  • 支持不同编码的读/写文件

  • 使用 base64 编码/解码处理二进制文件

  • 使用模式和正则表达式搜索文件中的文本内容

  • 检查文件存在并获取文件元数据

  • 自动创建目录结构

构建和测试

  • 使用可自定义的选项构建项目

  • 运行测试并报告详细的故障

  • 分析代码以查找潜在问题

  • 清理构建目录

  • 存档项目以供分发

CocoaPods 集成

  • 在项目中初始化 CocoaPods

  • 安装和更新 Pod

  • 添加和删除 pod 依赖项

  • 执行任意 pod 命令

Swift 包管理器

  • 初始化新的 Swift 包

  • 添加和删除具有各种版本要求的软件包依赖项

  • 更新软件包并解决依赖关系

  • 使用 DocC 为 Swift 软件包生成文档

  • 运行测试并构建 Swift 包

iOS模拟器工具

  • 列出可用的模拟器及其详细信息

  • 启动和关闭模拟器

  • 在模拟器上安装和启动应用程序

  • 截取屏幕截图并录制视频

  • 管理模拟器设置和状态

Xcode 实用程序

  • 通过 xcrun 执行 Xcode 命令

  • 编译资产目录

  • 从源图像生成应用程序图标集

  • 跟踪应用程序性能

  • 导出并验证存档以供 App Store 提交

  • 在不同的 Xcode 版本之间切换

Related MCP server: Xcode MCP Server

安装

先决条件

  • 安装了 Xcode 14.0 或更高版本的 macOS

  • Node.js 16 或更高版本

  • npm 或 yarn

  • Swift 5.5+ 的 Swift 包管理器功能

  • CocoaPods（可选，用于 CocoaPods 集成）

设置

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

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

# Make the script executable chmod +x setup.sh # Run the setup script ./setup.sh

安装脚本的作用：

  1. 环境验证：

    • 检查您是否在 macOS 上运行

    • 验证 Xcode 是否已安装并可访问

    • 确认 Node.js (v16+) 和 npm 可用

    • 检查 Ruby 安装

    • 验证 CocoaPods 安装（如果缺失则提供安装）

  2. 依赖项安装：

    • 运行npm install来安装所有必需的 Node.js 包

    • 执行npm run build来编译 TypeScript 代码

  3. 配置设置：

    • 如果不存在则创建一个.env文件

    • 提示输入项目基目录

    • 询问您是否要启用调试日志记录

    • 保存您的配置偏好

  4. Claude 桌面集成（可选）：

    • 提供为 Claude Desktop 配置服务器

    • 创建或更新 Claude Desktop 配置文件

    • 设置适当的命令和参数来启动服务器

何时使用安装脚本：

  • 首次安装以确保满足所有先决条件

  • 当您需要使用交互式提示进行引导配置时

  • 如果你想快速设置 Claude Desktop 集成

  • 验证您的环境是否具有所有必需的组件

该脚本将通过清晰的提示和有用的反馈指导您完成配置过程。

选项 2：手动设置

何时使用手动设置：

  • 您更喜欢明确控制每个安装步骤

  • 您有一个自定义环境或非标准配置

  • 您正在设置 CI/CD 管道或自动化环境

  • 您想要自定义安装过程的特定方面

  • 您是一位熟悉 Node.js 项目的经验丰富的开发人员

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

  1. 克隆存储库：

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

  2. 验证先决条件（必须安装这些）：

    • Xcode 和 Xcode 命令行工具

    • Node.js v16 或更高版本

    • npm

    • Ruby（用于 CocoaPods 支持）

    • CocoaPods（可选，用于与 pod 相关的功能）

  3. 安装依赖项：

    npm install

  4. 构建项目：

    npm run build

  5. 创建配置文件：

    # Option A: Start with the example configuration cp .env.example .env # Option B: Create a minimal configuration echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env echo "DEBUG=false" >> .env

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

  6. 对于 Claude Desktop 集成（可选）：

    • 编辑或创建~/Library/Application Support/Claude/claude_desktop_config.json

    • 添加以下配置（根据需要调整路径）：GXP6

设置故障排除

常见设置问题：

  1. 构建错误：

    • 确保您拥有正确的 Node.js 版本（v16+）

    • 尝试删除node_modules并再次运行npm install

    • 使用npx tsc --noEmit检查 TypeScript 错误

    • 确保代码中的所有导入都得到正确解析

  2. 缺少依赖项：

    • 如果您看到有关缺少模块的错误，请再次运行npm install

    • 对于本机依赖项，您可能需要 Xcode 命令行工具： xcode-select --install

  3. 权限问题：

    • 确保您对安装目录具有写入权限

    • 对于 CocoaPods 安装，您可能需要使用sudo gem install cocoapods

  4. 配置问题：

    • 验证您的.env文件具有正确的格式和有效的路径

    • 确保PROJECTS_BASE_DIR指向现有目录

    • 检查路径不包含需要转义的特殊字符

  5. Claude 桌面集成：

    • 确保 Claude 配置中的路径指向index.js的正确位置

    • 更改配置后重新启动 Claude Desktop

    • 在尝试使用 Claude 之前，请检查服务器是否正在运行

用法

启动服务器

npm start

对于自动重启的开发模式：

npm run dev

配置选项

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

  1. .env文件中的环境变量：

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

  2. 命令行参数：

    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 助手兼容。连接方法如下：

  1. 启动 Xcode MCP 服务器

  2. 配置你的AI助手使用服务器URL（通常为http://localhost:3000 ）

  3. AI 助手现在可以访问服务器提供的所有 Xcode 工具

工具文档

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

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

常见工作流程

建立新项目

// Create a new iOS app project await tools.create_xcode_project({ name: "MyAwesomeApp", template: "ios-app", outputDirectory: "~/Projects", organizationName: "My Organization", organizationIdentifier: "com.myorganization", language: "swift", includeTests: true, setAsActive: true }); // Add a Swift Package dependency await tools.add_swift_package({ url: "https://github.com/Alamofire/Alamofire.git", version: "from: 5.0.0" });

使用文件

// Read a file with specific encoding const fileContent = await tools.read_file({ filePath: "MyAwesomeApp/AppDelegate.swift", encoding: "utf-8" }); // Write to a file await tools.write_file({ path: "MyAwesomeApp/NewFile.swift", content: "import Foundation\n\nclass NewClass {}\n", createIfMissing: true }); // Search for text in files const searchResults = await tools.search_in_files({ directory: "MyAwesomeApp", pattern: "*.swift", searchText: "class", isRegex: false });

构建和测试

// Build the project await tools.build_project({ scheme: "MyAwesomeApp", configuration: "Debug" }); // Run tests await tools.test_project({ scheme: "MyAwesomeApp", testPlan: "MyAwesomeAppTests" });

项目结构

xcode-mcp-server/ ├── src/ │ ├── index.ts # Entry point │ ├── server.ts # MCP server implementation │ ├── types/ # Type definitions │ │ └── index.ts # Core type definitions │ ├── utils/ # Utility functions │ │ ├── errors.js # Error handling classes │ │ ├── pathManager.ts # Path validation and management │ │ ├── project.js # Project utilities │ │ └── simulator.js # Simulator utilities │ └── tools/ # Tool implementations │ ├── project/ # Project management tools │ │ └── index.ts # Project creation, detection, file adding │ ├── file/ # File operation tools │ │ └── index.ts # File reading, writing, searching │ ├── build/ # Build and testing tools │ │ └── index.ts # Building, testing, analyzing │ ├── cocoapods/ # CocoaPods integration │ │ └── index.ts # Pod installation and management │ ├── spm/ # Swift Package Manager tools │ │ └── index.ts # Package management and documentation │ ├── simulator/ # iOS simulator tools │ │ └── index.ts # Simulator control and interaction │ └── xcode/ # Xcode utilities │ └── index.ts # Xcode version management, asset tools ├── docs/ # Documentation │ ├── tools-overview.md # Comprehensive tool documentation │ └── user-guide.md # Usage examples and best practices ├── tests/ # Tests └── dist/ # Compiled code (generated)

工作原理

Xcode MCP 服务器使用模型上下文协议 (MCP) 为 AI 模型与 Xcode 项目交互提供标准化接口。该服务器架构由以下几个关键组件设计而成：

核心组件

  1. 服务器实现：处理工具注册和请求处理的主要 MCP 服务器。

  2. 路径管理：通过验证所有路径是否与允许的目录一致，确保文件访问的安全。

  3. 项目管理：检测、加载和管理不同类型的 Xcode 项目：

    • 标准 Xcode 项目（.xcodeproj）

    • Xcode 工作区（.xcworkspace）

    • Swift 包管理器项目（Package.swift）

  4. 目录状态：维护相对路径解析的活动目录上下文。

  5. 工具注册表：将工具组织成逻辑类别，以用于不同的 Xcode 操作。

请求流程

  1. AI助手向MCP服务器发送工具执行请求。

  2. 服务器验证请求参数和权限。

  3. 使用经过验证的参数调用适当的工具处理程序。

  4. 该工具执行请求的操作，通常使用本机 Xcode 命令。

  5. 结果被格式化并返回给AI助手。

  6. 全面的错误处理为故障排除提供了有意义的反馈。

安全功能

  • 路径验证：所有文件操作都限制在允许的目录中。

  • 错误处理：详细的错误消息有助于诊断问题。

  • 参数验证：使用 Zod 模式验证输入参数。

  • 流程管理：通过适当的错误处理，外部流程可以安全执行。

项目类型支持

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

  • 标准项目：直接 .xcodeproj 操作

  • 工作区：管理工作区内的多个项目

  • SPM 项目：处理 Swift 包管理器特定的操作

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

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

  1. 分叉存储库

  2. 创建你的功能分支（ git checkout -b feature/amazing-feature ）

  3. 提交您的更改（ git commit -m 'Add some amazing feature' ）

  4. 推送到分支（ git push origin feature/amazing-feature ）

  5. 打开拉取请求

开发指南

  • 遵循现有的代码风格和组织

  • 添加带有特定错误消息的全面错误处理

  • 为新功能编写测试

  • 更新文档以反映您的更改

  • 确保与不同项目类型（标准、工作区、SPM）的兼容性

添加新工具

要向服务器添加新工具：

  1. 在src/tools/目录中确定适当的类别

  2. 使用 Zod 模式验证的现有模式来实现该工具

  3. 在类别的index.ts文件中注册该工具

  4. 添加带有特定错误消息的错误处理

  5. 在适当的文档文件中记录该工具

故障排除

常见问题

  • 路径访问错误：确保您尝试访问的路径在允许的目录内

  • 构建失败：检查 Xcode 命令行工具是否已安装且为最新版本

  • 未找到工具：验证工具名称是否正确且已正确注册

  • 参数验证错误：检查工具文档中的参数类型和要求

调试

  1. 启动启用调试日志记录的服务器： npm start -- --debug

  2. 检查控制台输出以获取详细的错误消息

  3. 检查服务器日志以获取请求和响应详细信息

  4. 对于特定于工具的问题，请尝试直接在终端中运行等效的 Xcode 命令

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

  • 感谢模型上下文协议团队提供的 MCP SDK

  • 使用 TypeScript 和 Node.js 构建

  • 使用 Xcode 命令行工具和 Swift 包管理器

  • 特别感谢所有帮助改善服务器功能和稳健性的贡献者

One-click Deploy
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/r-huijts/xcode-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server