Peekaboo MCP – lightning-fast macOS screenshots for AI agents

Peekaboo 🫣 — 能看见屏幕并执行点击的 Mac 自动化工具。

Peekaboo 是一款 macOS 命令行工具和菜单栏应用，可用于屏幕捕获、辅助功能检查和原生 UI 自动化。你可以直接使用它，让它的 Agent 规划多步工作，也可以将同一套工具提供给 MCP 客户端。

安装

已发布的 CLI 和应用要求 macOS 15 或更高版本。

使用 Homebrew 安装 CLI

brew install openclaw/tap/peekaboo

使用 npm 安装 MCP 包

npm 包要求 Node.js 22 或更高版本，并包含 CLI 和 MCP 启动器。

npx -y @steipete/peekaboo --version

请参阅 MCP 设置，了解如何将其连接到 Codex、Claude Code、Cursor 或其他 MCP 客户端。

Mac 应用

从最新的 GitHub 发布版本下载已签名的 DMG。菜单栏应用提供权限引导、视觉反馈和 Agent 会话；如果还需要在 PATH 上使用 peekaboo，请另行安装 CLI。

有关源代码构建和其他安装方式的详情，请参阅安装指南。

快速入门

查看 Peekaboo 可用的权限，然后截取屏幕截图：

peekaboo permissions status
peekaboo see --no-elements --mode screen --path /tmp/peekaboo-screen.png

屏幕捕获需要“屏幕录制”权限。“辅助功能”权限可启用 UI 检查和控制；权限指南介绍了设置方法，以及模拟输入所需的额外权限。

检查正在运行的应用，以获取包含不透明元素 ID 的结构化 UI 映射：

peekaboo see --app Finder --json

这就是核心流程：观察当前屏幕，从结果中选择一个元素，然后对其执行操作。

4.9.7 版本更新

Peekaboo 4.9.7 是一个修复版本。现在，通过守护进程执行 window close 时，如果应用仍保留已关闭的窗口，也会报告成功；see 现在适用于标题包含应用名称或被截断的 Chrome 窗口；window close --foreground 可处理会自行重新执行的应用；dock list 则会隐藏分隔符。在 Mac 应用中，如果你排队发送后续消息，聊天会将流式回答保持在一起；失败的工具会显示为失败；即使提供方未声明支持视觉功能，也会使用已保存的 Vision 模型；Inspector 则会在每个显示器上高亮你实际指向的控件。

自动化应用

列出 Safari 的窗口，复制目标窗口的 window_id（下方为 12345），然后让整个交互始终固定在该窗口中：

peekaboo window list --app Safari --json
peekaboo click "Address and search bar" --app Safari --window-id 12345
peekaboo type "github.com/openclaw/Peekaboo" --app Safari --window-id 12345
peekaboo press Return --app Safari --window-id 12345

如果 Peekaboo 能解析进程，定向语义输入和定向 CLI 输入会在后台执行，因此应用无需切换到最前端。指定精确窗口选择器时，原始 CLI press 组合键也可以在后台执行。CLI 还接受最新的精确非对话框快照；后台专用 Agent/MCP 策略要求提供此快照。仅指定应用/PID 或未指定目标的组合键需要明确的前台授权，Agent/MCP 仅指定窗口选择器的组合键也需要授权。若有语义操作（例如 menu click），请优先使用。有关元素 ID、坐标、快照、等待和输入行为，请参阅自动化指南。

Agent 和 MCP

Agent 将相同的观察和操作工具组合起来，执行自然语言任务：

peekaboo agent "Open Safari, go to github.com, and search for Peekaboo" --allow-foreground

Agent 运行需要配置模型提供方。有关提供方和会话，请参阅 Agent 设置；有关向其他客户端开放 Peekaboo 的工具，请参阅 MCP 设置。

命令一览

目标	命令	指南
观察桌面	see、screen list、window list	捕获和检查
与 UI 交互	click、type、press、scroll、drag、set-value、action	自动化
控制 macOS	app、window、menu、menubar、dock、dialog、space	命令参考
运行工作流	agent、capture	Agent · 捕获
与客户端集成	mcp、browser、tools	MCP

运行 peekaboo help <command> 查看实时 CLI 帮助。完整命令索引列出了每个命令的标志、示例和故障排除信息。

配置

Peekaboo 将提供方凭据和设置存储在 ~/.peekaboo 下。使用 peekaboo config 查看或更改设置，并参阅配置指南了解配置文件、环境变量和自定义提供方。提供方参考介绍了托管、兼容和本地模型后端。

zsh、bash 和 fish 的 Shell 补全通过 peekaboo completions 提供；有关持久化设置，请参阅补全指南。

了解更多

• 项目方向
• 平台支持
• 架构
• 从源代码构建
• 测试
• Agent 聊天循环
• 命令参考

社区

• PeekabooWin — 以 Windows 为先的 Peekaboo 自动化循环重写版本（JavaScript + PowerShell），作者：@FelixKruger
• PeekabooX — 以 Linux 为先的 Peekaboo 自动化循环重写版本（Rust + Python），作者：@nordbyte

开发

从源代码构建需要 macOS 15 或更高版本、Swift 6.2 或更高版本、Node.js 22 或更高版本，以及仓库的子模块。

pnpm install --frozen-lockfile
pnpm run build:cli
pnpm run lint:docs
pnpm run test:safe

有关构建、签名和测试的更多详情，请参阅 docs/building.md。

许可证

MIT。请参阅 LICENSE。