s
steipete/Peekaboo
Peekaboo is a macOS CLI & optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.
aimacosmcpscreenshotsswift
SwiftMIT创建于 2025/5/22更新于 今天
README
由 Gemini 翻译整理
Peekaboo 🫣 - 能够识别屏幕并执行点击操作的 Mac 自动化工具
-0078d7?logo=apple&logoColor=white&style=flat-square){kind=icon}
Peekaboo 为 macOS 带来了高保真屏幕捕获、AI 分析以及完整的 GUI 自动化功能。第 3 版新增了原生的 Agent 流程，并支持跨 CLI 和 MCP server 的多屏幕自动化。
注意：v3 目前处于测试阶段（3.0.0-beta4），存在少量已知问题；详情请参阅更新日志。
主要功能
- 像素级精准捕获（窗口、屏幕、菜单栏），支持可选的 Retina 2x 缩放。
- 支持自然语言的 Agent，可串联 Peekaboo 工具链（查看、点击、输入、滚动、热键、菜单、窗口、应用、程序坞、空间）。
- 支持菜单和菜单栏的结构化 JSON 识别；无需物理点击。
- 多模型支持：GPT-5.1 系列、Claude 4.x、Grok 4-fast（视觉版）、Gemini 2.5 以及本地 Ollama 模型。
- 提供适用于 Claude Desktop 和 Cursor 的 MCP server 以及原生 CLI；两者使用相同的工具集。
- 可配置、可测试的工作流，支持可复现的会话及严格的类型检查。
- 需要 macOS 的“屏幕录制”和“辅助功能”权限（详见 docs/permissions.md）。
安装
- macOS 应用 + CLI (Homebrew):
brew install steipete/tap/peekaboo - MCP server (Node 22+，无需全局安装):
npx -y @steipete/peekaboo
快速上手
# 以 Retina 分辨率捕获全屏并保存到桌面
peekaboo image --mode screen --retina --path ~/Desktop/screen.png
# 通过标签点击按钮（一次性完成捕获、解析和点击）
peekaboo see --app Safari --json | jq -r '.data.snapshot_id' | read SNAPSHOT
peekaboo click --on "Reload this page" --snapshot "$SNAPSHOT"
# 运行自然语言自动化任务
peekaboo "Open Notes and create a TODO list with three items"
# 作为 MCP server 运行 (适用于 Claude/Cursor)
npx -y @steipete/peekaboo
# 极简 Claude Desktop 配置片段 (Developer → Edit Config):
# {
# "mcpServers": {
# "peekaboo": {
# "command": "npx",
# "args": ["-y", "@steipete/peekaboo"],
# "env": {
# "PEEKABOO_AI_PROVIDERS": "openai/gpt-5.1,anthropic/claude-opus-4"
# }
# }
# }
# }
| 命令 | 关键标志 / 子命令 | 说明 |
|---|---|---|
| see | --app, --mode screen/window, --retina, --json | 捕获并标注 UI，返回快照 + 元素 ID |
| click | --on , --snapshot, --wait, coords | 通过元素 ID、标签或坐标进行点击 |
| type | --text, --clear, --delay-ms | 输入文本，支持节奏设置 |
| press | key names, --repeat | 特殊按键和序列 |
| hotkey | combos like cmd,shift,t | 组合键（cmd/ctrl/alt/shift） |
| scroll | --on , --direction up/down, --ticks | 滚动视图或元素 |
| swipe | --from/--to, --duration, --steps | 平滑手势拖拽 |
| drag | --from/--to, modifiers, Dock/Trash targets | 在元素/坐标间进行拖放 |
| move | --to , --screen-index | 移动光标但不点击 |
| window | list, move, resize, focus, set-bounds | 移动/调整窗口大小/聚焦窗口和空间 |
| app | launch, quit, relaunch, switch, list | 启动、退出、重启、切换应用 |
| space | list, switch, move-window | 列出或切换 macOS 空间 |
| menu | list, list-all, click, click-extra | 列出/点击应用菜单和附加项 |
| menubar | list, click | 按名称/索引定位状态栏项 |
| dock | launch, right-click, hide | 程序坞相关操作 |