Xcode MCP Server

Drew 的 Xcode MCP 服务 (drews-xcode-mcp)

一个 MCP（Model Context Protocol）服务，可让 AI 助手控制并使用 Xcode 进行 Apple 平台开发。

已从 xcode-mcp-server 更名。 由于多个互不相关的项目共用这个名称，而且 Xcode 现在也自带 MCP 服务，因此本项目现已更名为 drews-xcode-mcp。**现有配置仍可正常使用：**旧的 PyPI 名称是一个转发到本项目的兼容包，所有设置也会保留。方便时，请更新 MCP 配置以运行 drews-xcode-mcp。如果你的服务键名是旧的默认值 xcode-mcp-server，我们也建议将其改为 drews-xcode-mcp——别忘了更新引用旧工具名称的工具权限允许列表（mcp__xcode-mcp-server__* 改为 mcp__drews-xcode-mcp__*）。如果你使用的是自定义键名，请保留原样，工具权限不受影响。

功能

此服务可让 AI 助手（例如 Claude、Cursor 或其他 MCP 客户端）：

• 发现和浏览 Xcode 项目及源文件
• 构建和运行 iOS、macOS、tvOS 和 watchOS 应用
• 执行和监控测试，并获取详细结果
• 调试构建失败，获取错误和警告信息
• 捕获控制台输出，查看正在运行的应用
• 截取屏幕截图，获取 Xcode 窗口和 iOS 模拟器的画面
• 管理模拟器并查看其状态

AI 可以执行完整的开发工作流——从查找项目到构建、运行测试、调试故障并捕获结果。

要求

• macOS——此服务仅适用于 macOS
• Xcode——必须安装 Xcode
• Python 3.10+——用于运行服务（如果系统上的 Python 版本较旧，uvx 会自动获取兼容版本）

安全性

此服务通过基于路径的安全机制控制可访问的目录：

• **设置访问限制：**设置 XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3，将访问范围限制为指定目录
• **默认设置：**如果未指定，则允许访问你的主目录（$HOME）

安全要求：

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

设置

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

which uv || brew install uv

1. Claude Code（推荐）

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

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

# Example: How to run v1.3.0b6
claude mcp add --scope user --transport stdio -- drews-xcode-mcp `which uvx` drews-xcode-mcp==1.3.0b6

就是这样！Claude Code 会自动处理后续步骤。

2. Claude Desktop

编辑 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

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

如果你只想让 drews-xcode-mcp 访问指定的项目或文件夹，可以添加 env 选项，并提供以冒号分隔的绝对文件夹路径，如下所示：

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

3. Cursor AI

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

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

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

**可选：**添加 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 - 添加允许访问的文件夹（可重复使用）

示例：

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

**注意：**使用 MCP 客户端（Claude、Cursor）时，请改为在客户端配置文件的 env 部分进行配置。

开发

此服务基于 FastMCP 构建，并使用 AppleScript 与 Xcode 通信。

本地测试

使用 MCP Inspector 进行测试：

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

这会打开一个检查器界面，你可以在其中直接测试工具。提供路径时，请使用带引号的字符串："/Users/you/Projects/MyApp.xcodeproj"

限制

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