AI导哈

Xcode MCP工具套件

提供SDK、CLI和代理工具，用于通过Xcode的Model Context Protocol（MCP）访问和操作Xcode的20种工具，支持项目构建、测试运行、Swift REPL会话、SwiftUI预览捕获等功能。

  • by kleinpanic
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 kleinpanic/xcode-mcp-suite

使用说明

xcode mcp套件

Xcode代理编码桥的SDK、CLI和MCP代理(xcrun mcpbridge).

Xcode 26.3+公开 20个MCP工具 让AI编码代理构建项目、运行测试、执行Swift REPL会话、捕获SwiftUI预览、导航符号和控制模拟器——所有这些都是通过 模型上下文协议.

该套件使这些工具易于从任何代理或脚本中使用：

包装 它的作用
@kleinpanic/xcode-mcp-sdk TypeScript SDK——完全类型化 XcodeClient & XcodeSession
@kleinpanic/xcmcp CLI-- xcmcp build, test, repl, screenshot, preview…
@kleinpanic/xcode-mcp-proxy 独立MCP代理-- npx 将其导入任何MCP客户端

苹果官方文件： 允许外部代理编码工具访问Xcode

先决条件

  1. Xcode 26.3+ 在目标macOS主机上
  2. 启用网桥： Xcode→ 设置→ 智能→ 模型上下文协议→ Xcode工具：打开
  3. SSH访问主机（用于远程使用）

快速开始

命令行界面

npm install -g @kleinpanic/xcmcp

# Check everything works
xcmcp doctor --host collins-pro

# Build, test, repl
xcmcp build --host collins-pro
xcmcp test --host collins-pro
xcmcp repl --host collins-pro 'print("Hello from Swift")'

# Screenshot a booted simulator
xcmcp screenshot --host collins-pro --mode simulator --out /tmp/ui.png

软件开发工具包

npm install @kleinpanic/xcode-mcp-sdk

import { withXcodeSession } from "@kleinpanic/xcode-mcp-sdk";

await withXcodeSession({ host: "collins-pro" }, async (session) => {
  // tabIdentifier is managed automatically
  const result = await session.buildProject();
  console.log(`Build: ${result.success ? "✓" : "✗"}`);

  const tests = await session.runAllTests();
  console.log(`Tests: ${tests.passed} passed, ${tests.failed} failed`);
});

MCP代理（插入任何MCP客户端）

# Claude Code
claude mcp add --transport stdio xcode -- npx @kleinpanic/xcode-mcp-proxy

# Codex CLI
codex mcp add xcode -- npx @kleinpanic/xcode-mcp-proxy

# OpenClaw (mcporter)
mcporter add stdio xcode "npx @kleinpanic/xcode-mcp-proxy"

集 XCODE_HOST=collins-pro 在您的环境中，它通过SSH自动连接。

全部20个Xcode MCP工具

类别 工具
文件操作 XcodeRead · XcodeWrite · XcodeUpdate · XcodeGlob · XcodeGrep · XcodeLS · XcodeMakeDir · XcodeRM · XcodeMV
构建与测试 BuildProject · GetBuildLog · RunAllTests · RunSomeTests · GetTestList
诊断 XcodeListNavigatorIssues · XcodeRefreshCodeIssuesInFile
代码执行 ExecuteSnippet
预览 RenderPreview
文档 DocumentationSearch
窗口 XcodeListWindows ⭐ （先打电话）

SDK使用

XcodeClient --直接、低级访问

import { XcodeClient } from "@kleinpanic/xcode-mcp-sdk";

const client = new XcodeClient({ host: "collins-pro" });
await client.connect();

// Always get tabIdentifier first
const { windows } = await client.listWindows();
const tabId = windows[0]["tabIdentifier"];

// Build
const build = await client.buildProject({ "tabIdentifier": tabId });

// Swift REPL
const repl = await client.runSwiftREPL({
  "tabIdentifier": tabId,
  code: 'let arr = [1,2,3].map { $0 * 2 }; print(arr)',
});
console.log(repl.output); // [2, 4, 6]

// SwiftUI preview → base64 PNG
const preview = await client.getSwiftUIPreview({
  "tabIdentifier": tabId,
  filePath: "Sources/Views/ContentView.swift",
});

await client.disconnect();

XcodeSession --管理会话（推荐）

import { XcodeSession, XcodeConnectionError } from "@kleinpanic/xcode-mcp-sdk";

const session = new XcodeSession({
  host: "collins-pro",
  projectPath: "MyApp",   // auto-selects matching window
});

await session.connect();

// No tabIdentifier needed — managed automatically
const result = await session.buildProject({ scheme: "MyApp" });
const refs = await session.getReferencesForSymbol({ symbol: "ContentView" });
const info = await session.getSymbolInfo({ symbol: "body" });

session.disconnect();

错误处理

import { XcodeBuildError, XcodeConnectionError, XcodeToolError } from "@kleinpanic/xcode-mcp-sdk";

try {
  await session.buildProject();
} catch (e) {
  if (e instanceof XcodeBuildError) {
    for (const issue of e.issues) {
      console.error(`${issue.file}:${issue.line} — ${issue.message}`);
    }
  } else if (e instanceof XcodeConnectionError) {
    console.error("Xcode not reachable — is it running?");
  }
}

CLI参考

xcmcp <command> [options]

Commands:
  connect    Verify SSH + Xcode availability
  doctor     Full preflight check
  list-tools List all 20 MCP tools
  call       Call any tool with JSON args
  build      Build the active project
  test       Run all tests
  clean      Clean build folder
  screenshot Capture simulator or screen PNG
  repl       Run Swift code in REPL
  preview    Render SwiftUI preview to PNG
  windows    List open Xcode windows

Options:
  --host <h>     Remote macOS host (default: $XCODE_HOST)
  --scheme <s>   Xcode scheme override
  --mode         screenshot mode: simulator|screen
  --out <path>   Output path for PNG files
  --file <path>  Swift file for preview command
  --json         Raw JSON output

完整手册页： man xcmcp （安装后）或 man/xcmcp.1

代理集成指南

AGENTS.md/CLAUDE.md代码片段

将此添加到代理的引导文件中：

## Xcode MCP Tools

Xcode MCP tools are available when XCODE_HOST is set.
Use `xcmcp doctor` to verify connectivity before starting iOS/macOS work.
Always call XcodeListWindows first to get a tabIdentifier.
See: https://github.com/kleinpanic/xcode-mcp-suite

典型的代理工作流程

1. xcmcp doctor --host $XCODE_HOST          # preflight
2. xcmcp windows --host $XCODE_HOST         # get tabIdentifier
3. xcmcp build --host $XCODE_HOST           # build → fix errors
4. xcmcp test --host $XCODE_HOST            # run tests
5. xcmcp preview --file ContentView.swift   # visual audit
6. xcmcp repl 'MyModel().validate()'        # spot-check logic

例子

看 示例/ 对于完整的可运行脚本：

发展

pnpm install
pnpm build
pnpm test
pnpm typecheck

文档

许可证

麻省 理工© 小恐慌

视觉交互（模拟器）

CLI包括 ui 用于查看正在运行的模拟器并与之交互的子命令——启用完整的可视化代理循环：

# See: capture simulator state
xcmcp screenshot --host collins-pro --mode simulator --out /tmp/snap.png
# → feed PNG to image/vision tool for coordinate analysis

# Interact: tap, type, swipe
xcmcp ui tap   --host collins-pro 195 420
xcmcp ui type  --host collins-pro "hello world"
xcmcp ui swipe --host collins-pro 200 600 200 200
xcmcp ui key   --host collins-pro 36        # Return

# Log: stream live app output
xcmcp ui log --host collins-pro

循环： 截图→ 分析坐标→ 互动→ 截图→ 验证

相关 MCP