Xcode MCP 服务器

一个 Model Context Protocol (MCP) 服务器，使 AI 助手能够控制并与 Xcode 进行交互，用于苹果平台的开发。

功能概述

此服务器允许 AI 助手（如 Claude、Cursor 或其他 MCP 客户端）执行以下操作：

• 发现和导航您的 Xcode 项目和源文件
• 构建和运行iOS、macOS、tvOS 和 watchOS 应用程序
• 执行和监控测试并获取详细的测试结果
• 调试构建失败通过检索错误和警告信息
• 捕获控制台输出来自正在运行的应用程序
• 截取屏幕截图Xcode 窗口和 iOS 模拟器
• 管理模拟器并查看其状态

AI 可以完成完整的开发工作流程——从找到项目到构建它，运行测试，调试失败，并捕获结果。

要求

• macOS - 此服务器仅在 macOS 上运行
• Xcode - 必须安装 Xcode
• Python 3.8+ - 用于运行服务器

安全性

服务器实现了基于路径的安全机制来控制哪些目录是可访问的：

• 受限模式： 设置 XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3 以限制对特定目录的访问
• 默认模式： 如果未指定，则允许访问您的主目录 ($HOME)

安全要求：

• 所有路径必须是绝对路径（以 / 开头）
• 不允许使用 .. 路径组件
• 所有路径必须存在且为目录

配置

首先，确保已安装 uv（所有方法都需要）：

which uv || brew install uv

1. Claude Code（推荐）

claude mcp add --scope user --transport stdio -- xcode-mcp-server `which uvx` xcode-mcp-server

要运行特定版本，请使用：

# 示例：如何运行 v1.3.0b6
claude mcp add --scope user --transport stdio -- xcode-mcp-server `which uvx` xcode-mcp-server==1.3.0b6

就这样！Claude Code 将自动处理其余部分。

2. Claude Desktop

编辑您的 Claude Desktop 配置文件 (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
    "mcpServers": {
        "xcode-mcp-server": {
            "command": "uvx",
            "args": [
                "xcode-mcp-server"
            ]
        }
    }
}

如果您希望只允许某些项目或文件夹被 xcode-mcp-server 访问，可以添加 env 选项，用冒号分隔的绝对文件夹路径列表，如下所示：

{
    "mcpServers": {
        "xcode-mcp-server": {
            "command": "uvx",
            "args": [
                "xcode-m-mp-server"
            ],
            "env": {
                "XCODEMCP_ALLOWED_FOLDERS": "/Users/andrew/my_project:/Users/andrew/Documents/source"
            }
        }
    }
}

3. Cursor AI

在 Cursor 中：设置 → 工具与集成 → + 新 MCP 服务器

或者直接编辑 ~/.cursor/mcp.json：

{
    "mcpServers": {
        "xcode-mcp-server": {
            "command": "uvx",
            "args": ["xcode-mcp-server"]
        }
    }
}

可选： 添加文件夹限制，使用 env 部分（与 Claude Desktop 相同格式）。

使用

配置完成后，只需请求您的 AI 助手帮助您进行 Xcode 任务：

• "查找我主目录中的所有 Xcode 项目"
• "构建位于 /path/to/MyProject.xcodeproj 的项目"
• "为此项目运行测试并显示任何失败"
• "这个项目有哪些构建错误？"
• "显示这个项目的目录结构"
• "截取 Xcode 窗口的屏幕截图"

大多数工具都支持 .xcodeproj 或 .xcworkspace 文件的路径，或者使用常规目录路径进行浏览和导航。

高级配置

命令行参数

当直接运行服务器（用于开发或自定义设置）时，这些选项可用：

构建输出控制：

• --no-build-warnings - 仅显示错误，排除警告
• --always-include-build-warnings - 始终显示警告（默认）

通知：

• --show-notifications - 启用 macOS 操作通知
• --hide-notifications - 禁用通知（默认）

访问控制：

• --allowed /path - 添加允许的文件夹（可以重复）

示例：

xcode-mcp-server --no-build-warnings --show-notifications --allowed ~/Projects

注意： 当使用 MCP 客户端（Claude、Cursor）时，应通过客户端配置文件中的 env 部分进行配置。

开发

服务器使用 FastMCP 构建，并使用 AppleScript 与 Xcode 通信。

本地测试

使用 MCP Inspector 测试：

export XCODEMCP_ALLOWED_FOLDERS=~/Projects
mcp dev xcode_mcp_server/__main__.py

这将打开一个检查器界面，在其中您可以直接测试工具。提供路径作为引号字符串："/Users/you/Projects/MyApp.xcodeproj"

限制

• AppleScript 语法可能需要针对特定的 Xcode 版本进行调整
• 某些操作需要先在 Xcode 中打开项目