内容
# Drew's Xcode MCP 服务器（drews-xcode-mcp）
[](https://pypi.org/project/drews-xcode-mcp/)
[](https://pypi.org/project/drews-xcode-mcp/)
[](https://pepy.tech/project/drews-xcode-mcp)
[](https://modelcontextprotocol.io)
[](https://www.apple.com/macos/)
[](https://developer.apple.com/xcode/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/drewster99/drews-xcode-mcp/commits)
一个 MCP（模型上下文协议）服务器，使 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 将自动获取兼容的 Python）
## 安全
服务器实施基于路径的安全性来控制可访问的目录：
- **有限制：** 设置 `XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3` 以限制对特定目录的访问
- **默认：** 如果未指定，则允许访问您的主目录（`$HOME`）
安全要求：
- 所有路径必须为绝对路径（以 `/` 开头）
- 不允许使用 `..` 路径组件
- 所有路径必须存在且为目录
## 安装
首先，确保已安装 `uv`（以下所有方法均需要）：
```bash
which uv || brew install uv
```
### 1. Claude Code（推荐）
```bash
claude mcp add --scope user --transport stdio -- drews-xcode-mcp `which uvx` drews-xcode-mcp
```
要运行特定版本，请使用：
```bash
# 示例：如何运行 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 桌面版
编辑您的 Claude 桌面版配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"drews-xcode-mcp": {
"command": "uvx",
"args": [
"drews-xcode-mcp"
]
}
}
}
```
如果您希望仅允许某些项目或文件夹可被 drews-xcode-mcp 访问，请添加 `env` 选项，并使用冒号分隔的绝对文件夹路径列表，如下所示：
```json
{
"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`：
```json
{
"mcpServers": {
"drews-xcode-mcp": {
"command": "uvx",
"args": ["drews-xcode-mcp"]
}
}
}
```
**可选：** 使用 `env` 部分添加文件夹限制（与上述 Claude 桌面版格式相同）。
## 使用
配置完成后，只需要求您的 AI 助手帮助您完成 Xcode 任务：
- "在我的主目录中查找所有 Xcode 项目"
- "构建位于 /path/to/MyProject.xcodeproj 的项目"
- "为此项目运行测试并显示任何失败结果"
- "此项目的构建错误是什么？"
- "显示此项目的目录结构"
- "截取 Xcode 窗口的截图"
大多数工具都使用 `.xcodeproj` 或 `.xcworkspace` 文件的路径，或使用常规目录路径进行浏览和导航。
## 高级配置
### 命令行参数
直接运行服务器时（用于开发或自定义设置），可使用以下选项：
**构建输出控制：**
- `--no-build-warnings` - 仅显示错误，排除警告
- `--always-include-build-warnings` - 始终显示警告（默认）
**通知：**
- `--show-notifications` - 启用 macOS 操作的通知
- `--hide-notifications` - 禁用通知（默认）
**访问控制：**
- `--allowed /path` - 添加允许的文件夹（可重复）
示例：
```bash
drews-xcode-mcp --no-build-warnings --show-notifications --allowed ~/Projects
```
**注意：** 使用 MCP 客户端（Claude、Cursor）时，请在客户端配置文件中的 `env` 部分配置这些参数。
## 开发
服务器使用 FastMCP 构建，并使用 AppleScript 与 Xcode 通信。
### 本地测试
使用 MCP 检验器进行测试：
```bash
export XCODEMCP_ALLOWED_FOLDERS=~/Projects
mcp dev drews_xcode_mcp/__main__.py
```
这将打开一个检验器界面，您可以在其中直接测试工具。提供路径时，请使用引号字符串：`"/Users/you/Projects/MyApp.xcodeproj"`
## 限制
- AppleScript 语法可能需要针对特定 Xcode 版本进行调整
- 某些操作要求项目首先在 Xcode 中打开
