MCP Baepsae

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

开发者工具操作系统自动化 #iOS模拟器 #macOS自动化 #UI测试 #MCP服务 .swift

评分 : 2.5分

下载量 : 4.1K

更新时间 : 2026-03-13

打开站点

什么是Baepsae MCP Server?

Baepsae是一个专门为iOS模拟器和macOS应用自动化设计的Model Context Protocol (MCP)服务器。它允许AI助手（如Claude、Codex等）直接与iOS模拟器中的应用程序以及macOS桌面应用进行交互，包括UI元素识别、点击、输入文本、截图、录屏等自动化操作。

如何使用Baepsae?

使用Baepsae非常简单：首先确保你的系统满足要求（macOS 14+、Xcode、Node.js），然后通过安装脚本一键配置到支持的AI客户端中。配置完成后，你就可以在AI助手中直接使用各种自动化命令来控制iOS模拟器和macOS应用。

适用场景

Baepsae特别适合以下场景： 1. iOS应用自动化测试和演示 2. macOS应用UI自动化操作 3. 应用原型快速交互测试 4. 自动化截图和录屏 5. 批量应用操作和配置

主要功能

iOS模拟器自动化

全面支持iOS模拟器的自动化操作，包括应用安装/启动/卸载、UI元素识别、点击、滑动、文本输入等。

macOS应用控制

直接控制macOS桌面应用，支持UI元素查找、点击、键盘输入、右键菜单、拖放等操作。

媒体捕获功能

支持iOS模拟器截图、屏幕录制和视频流捕获，方便记录自动化过程和生成演示材料。

多客户端支持

兼容多种AI客户端，包括Claude Desktop、Claude Code、Codex CLI、OpenCode、Gemini、GitHub Copilot等。

47个自动化工具

提供47个精心设计的自动化工具，涵盖UI交互、应用管理、系统操作等各个方面。

一键安装配置

提供智能安装脚本，自动检测和配置到所有支持的AI客户端，简化设置过程。

优势

强大的自动化能力：47个工具覆盖iOS模拟器和macOS应用的全面自动化需求

易于集成：支持多种主流AI客户端，一键安装配置

原生性能：Swift原生桥接提供高性能的UI交互能力

详细的UI识别：支持通过ID、标签、类型等多种方式识别UI元素

丰富的媒体功能：截图、录屏、视频流一应俱全

局限性

仅支持macOS平台：依赖macOS特有的框架和工具

需要Xcode环境：iOS模拟器功能需要Xcode或Xcode Command Line Tools

需要权限配置：自动化功能需要系统辅助功能权限

学习曲线：需要了解基本的iOS模拟器和macOS应用概念

如何使用

环境准备

确保你的系统满足以下要求： - macOS 14或更高版本 - Xcode或Xcode Command Line Tools - Node.js 18或更高版本 - Swift 6或更高版本

安装Baepsae

使用npm一键安装Baepsae MCP服务器：

配置AI客户端

运行安装脚本，自动配置到所有支持的AI客户端：

授予系统权限

在系统设置中授予辅助功能权限： 1. 打开系统设置 > 隐私与安全性 > 辅助功能 2. 启用你的AI客户端和终端应用 3. 如果找不到应用，点击+手动添加

开始使用

在配置好的AI客户端中，现在可以直接使用Baepsae的各种自动化命令了。

使用案例

iOS应用自动化测试

自动化测试iOS应用的登录流程，包括输入用户名密码、点击登录按钮、验证登录结果。

macOS应用批量操作

在多个macOS应用中执行相同的操作，如批量保存文件、批量导出数据等。

应用演示录制

自动执行应用操作流程并录制视频，用于制作产品演示或教程。

常见问题

为什么Baepsae只能在macOS上运行？

安装时出现'Missing native binary'错误怎么办？

为什么自动化点击操作没有效果？

如何查看所有可用的自动化工具？

支持哪些AI客户端？

如何卸载Baepsae？

🚀 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）需要辅助功能权限。

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

对于模拟器目标，基于选择器的操作（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。