shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

mcp-baepsae

mcp-baepsae是一个用于iOS模拟器和macOS应用自动化的本地MCP服务器，通过TypeScript MCP层和Swift原生桥接，提供UI检查、输入模拟、应用管理等工具。

article

README

🚀 mcp-baepsae

Baepsae（棕头鸦雀）是一种小巧的韩国鸟类，体型圆润、胖乎乎的，还总是蹦蹦跳跳地叽叽喳喳叫。它以坚韧不拔的精神著称，即便小鸟想跟上鹳的步伐，也绝不放弃。这个项目同样小巧，但它会不知疲倦地攻克你的模拟器难题。

这是一个用于iOS模拟器和macOS应用自动化的本地MCP服务器，具备TypeScript MCP层和Swift原生桥接功能。

韩语文档请参考 README-KR.md。

🚀 快速开始

本项目是用于iOS模拟器和macOS应用自动化的本地MCP服务器，支持多种客户端集成，下面将详细介绍使用前的准备工作、安装方法、配置步骤等内容。

✨ 主要特性

  • 具备TypeScript MCP层和Swift原生桥接，可用于iOS模拟器和macOS应用自动化。
  • 支持多种客户端，如Claude Code、Claude Desktop、Codex CLI等。
  • 提供丰富的工具命令，可进行UI检查、输入自动化等操作。

📦 安装指南

前提条件

  • macOS 14及以上版本。
  • 安装Xcode和iOS Simulator。
  • Node.js 18及以上版本。
  • Swift 6及以上版本。

安装方式

选项A) 使用npm（最简单）

# 无需安装直接运行
npx mcp-baepsae@latest

# 或者全局安装
npm install -g mcp-baepsae

在macOS上，Swift原生二进制文件会在安装过程中自动构建。如果没有安装Swift，服务器仍然可以使用基于simctl的功能。

选项B) 从源代码安装

git clone https://github.com/oozoofrog/mcp-baepsae.git
cd mcp-baepsae
npm install
npm run build

💻 使用示例

基础用法

模拟器应用可访问性快速入门（应用UI内）：

// 1) 在目标模拟器中启动应用
launch_app({ udid: "...", bundleId: "com.example.app" })

// 2) 检查或搜索可访问性树（默认在应用内容范围内）
sim_describe_ui({ udid: "..." })
sim_search_ui({ udid: "...", query: "Login" })

// 3) 通过可访问性标识符/标签进行交互
sim_tap({ udid: "...", id: "login-button" })

// 可选：在选择器查找中包含模拟器的系统UI
sim_tap({ udid: "...", label: "Home", all: true })

打开URL（iOS模拟器）：

// 打开Naver移动版
open_url({ udid: "...", url: "https://m.naver.com" })

管理应用（iOS模拟器）：

// 安装应用
install_app({ udid: "...", path: "/path/to/App.app" })

// 启动Safari
launch_app({ udid: "...", bundleId: "com.apple.mobilesafari" })

// 终止Safari
terminate_app({ udid: "...", bundleId: "com.apple.mobilesafari" })

macOS应用自动化：

// 列出正在运行的macOS应用
list_apps({})

// 对macOS应用进行截图
mac_screenshot_app({ bundleId: "com.apple.Safari" })

📚 详细文档

平台支持

| 平台 | 是否支持 | 说明 | |------|------|------| | macOS | 是 | 主要平台，iOS模拟器和辅助功能API需要此平台。 | | Linux | 否 | 原生二进制文件依赖AppKit、CoreGraphics和辅助功能框架。 | | Windows | 否 | 原生二进制文件依赖AppKit、CoreGraphics和辅助功能框架。 |

为什么仅支持macOS？

Swift原生桥接（baepsae-native）使用特定于macOS的框架（AppKit、CoreGraphics、辅助功能）与iOS模拟器和macOS应用进行交互。这些框架在Linux或Windows上不可用。TypeScript MCP层还依赖于xcrun simctl，它是Xcode命令行工具的一部分，仅在macOS上可用。

要求总结：

  • macOS 14或更高版本 —— iOS模拟器自动化和辅助功能API访问必需。
  • Xcode或Xcode命令行工具 —— 原生二进制文件的Swift 6+编译和xcrun simctl命令必需。
  • Node.js >= 18.0.0 —— 运行TypeScript MCP服务器必需。

权限

进行UI检查和输入自动化功能（使用sim_* / mac_*作用域的工具，如sim_describe_ui、mac_tap、sim_right_click）需要辅助功能权限。

  1. 打开 系统设置 > 隐私与安全 > 辅助功能。
  2. 启用实际使用的MCP客户端应用和终端，如果列表中显示运行时进程（node），也一并启用。
  3. 如果应用缺失，点击+并手动添加。

对于模拟器目标，基于选择器的操作（sim_tap / sim_right_click 配合id或label）默认在应用内内容中进行搜索。设置all: true可包含模拟器的系统UI。

MCP设置（推荐）

使用安装脚本直接调用每个客户端的MCP安装流程。

bash scripts/install.sh --tool all

客户端矩阵

| 客户端 | 安装路径 | 脚本目标 | 说明 | |------|------|------|------| | Claude Code | claude mcp add | --tool claude-code | 支持通过--claude-scope实现多作用域 | | Claude Desktop | claude mcp add --scope user | --tool claude-desktop | 用户级注册 | | Codex CLI | codex mcp add | --tool codex-cli | 也适用于Codex桌面版设置 | | Codex Desktop | Codex CLI MCP配置 | --tool codex-desktop | 使用与CLI相同的MCP注册表 | | OpenCode | 全局配置（~/.config/opencode/opencode.json） | --tool opencode | 由安装程序自动更新 | | Gemini | gemini mcp add | --tool gemini | 用户作用域设置 | | Google Antigravity | 与Gemini兼容的MCP流程 | --tool antigravity | 使用Gemini MCP命令路径 | | GitHub Copilot | copilot或gh copilot会话 | --tool copilot | 交互式/基于会话的设置 |

针对LLM的设置

如果你是一个LLM代理，要设置此MCP服务器，以下是你需要的所有内容：

快速开始（一条命令）

# 将baepsae注册为所有支持的客户端的MCP服务器
bash scripts/install.sh --tool all

如果你是通过npm安装而不是克隆仓库，使用npx：

# Claude Code
claude mcp add baepsae -- npx -y mcp-baepsae@latest

# Codex CLI
codex mcp add baepsae -- npx -y mcp-baepsae@latest

自动化标志

# 预览命令而不执行
bash scripts/install.sh --tool all --dry-run

# 验证环境和依赖项
bash scripts/install.sh --tool all --doctor

# 从所有客户端取消注册
bash scripts/install.sh --tool all --uninstall

运行时选项

安装程序通过--runtime支持多个运行时： | 标志 | 命令 | 使用场景 | |------|------|------| | --runtime node（默认） | node dist/index.js | 本地源代码构建 | | --runtime npx | npx -y mcp-baepsae@latest | npm注册表，无需全局安装 | | --runtime bunx | bunx mcp-baepsae@latest | Bun用户 | | --runtime global | mcp-baepsae | 在npm install -g mcp-baepsae之后 |

手动设置（备用方案）

当你不想运行scripts/install.sh时使用此方法。

使用npx（推荐给npm用户）

# Claude Code
claude mcp add baepsae -- npx -y mcp-baepsae@latest

# Codex CLI
codex mcp add baepsae -- npx -y mcp-baepsae@latest

# Gemini CLI
gemini mcp add --scope user --transport stdio baepsae npx -y mcp-baepsae@latest

使用本地构建

# Claude Code（项目）
claude mcp add --scope project --env="BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native" baepsae -- node /ABS/PATH/dist/index.js

# Codex CLI
codex mcp add baepsae --env BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native -- node /ABS/PATH/dist/index.js

# Gemini CLI
gemini mcp add --scope user --transport stdio -e BAEPSAE_NATIVE_PATH=/ABS/PATH/native/.build/release/baepsae-native baepsae node /ABS/PATH/dist/index.js

项目结构

  • MCP服务器入口点：src/index.ts
  • 工具模块：src/tools/（信息、模拟器、UI、输入、媒体、系统）
  • 共享实用工具：src/utils.ts，src/types.ts
  • 原生二进制文件入口点：native/Sources/main.swift
  • 原生命令处理程序：native/Sources/Commands/
  • 原生二进制文件输出：native/.build/release/baepsae-native
  • TS测试：tests/mcp.contract.test.mjs，tests/unit.test.mjs，tests/mcp.real.test.mjs
  • Swift测试：native/Tests/BaepsaeNativeTests/

命令

npm run build       # 构建TypeScript + 原生Swift二进制文件
npm test            # 契约/集成测试
npm run test:real   # 真实模拟器冒烟测试（需要已启动的模拟器）
npm run verify      # test + test:real
npm run setup:mcp   # scripts/install.sh的别名

MCP工具状态

共实现了47个端到端工具。

显式目标作用域工具（30个，推荐）

优先使用这些工具以避免模拟器/macOS目标的歧义。 | 模拟器作用域 | macOS作用域 | |------|------| | sim_describe_ui | mac_describe_ui | | sim_search_ui | mac_search_ui | | sim_tap | mac_tap | | sim_type_text | mac_type_text | | sim_swipe | mac_swipe | | sim_key | mac_key | | sim_key_sequence | mac_key_sequence | | sim_key_combo | mac_key_combo | | sim_touch | mac_touch | | sim_right_click | mac_right_click | | sim_scroll | mac_scroll | | sim_drag_drop | mac_drag_drop | | sim_list_windows | mac_list_windows | | sim_activate_app | mac_activate_app | | sim_screenshot_app | mac_screenshot_app |

仅适用于iOS模拟器（11个）

list_simulators，screenshot，record_video，stream_video，open_url，install_app，launch_app，terminate_app，uninstall_app，button，gesture

仅适用于macOS / 系统（4个）

list_apps，menu_action，get_focused_app，clipboard

实用工具（2个）

baepsae_help，baepsae_version

🔧 技术细节

  • 本项目使用Swift原生桥接（baepsae-native）与macOS特定框架（AppKit、CoreGraphics、辅助功能）交互，实现与iOS模拟器和macOS应用的自动化操作。
  • TypeScript MCP层依赖xcrun simctl，这是Xcode命令行工具的一部分，确保了在macOS上的兼容性。
  • 项目结构清晰，各个模块分工明确，便于开发和维护。

📄 许可证

文档中未提及许可证相关信息。

🛠️ 故障排除

  • Claude设置时出现Invalid environment variable format错误：
    • 使用当前脚本（scripts/install.sh）或claude mcp add --env="KEY=value" ...格式。
  • 出现Missing native binary错误：
    • 运行npm run build，并确认native/.build/release/baepsae-native存在。
  • OpenCode未显示baepsae：
    • 重新运行bash scripts/install.sh --tool opencode --skip-install --skip-build，并检查~/.config/opencode/opencode.json。
  • Copilot未自动注册：
    • Copilot MCP流程是交互式/基于会话的。使用--interactive重新运行安装程序。
  • 真实冒烟测试被跳过：
    • 先启动一个iOS模拟器，然后运行npm run test:real。
help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client