# Peekaboo — macOS Screenshots + Clicks (MCP)

> Peekaboo is a macOS CLI (optional MCP) for screenshots and click automation; verified 3,986★ and installs via Homebrew or `npx -y @steipete/peekaboo`.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

```bash
brew install steipete/tap/peekaboo
peekaboo image --mode screen --retina --path ~/Desktop/screen.png
# Or run as MCP server:
npx -y @steipete/peekaboo
```

## Intro

Peekaboo is a macOS CLI (optional MCP) for screenshots and click automation; verified 3,986★ and installs via Homebrew or `npx -y @steipete/peekaboo`.

**Best for:** Agent workflows that must see the screen, take evidence screenshots, and perform deterministic UI actions

**Works with:** macOS 15+ with Screen Recording + Accessibility permissions; MCP clients via npx

**Setup time:** 10-25 minutes

### Key facts (verified)

- GitHub: 3986 stars · 288 forks · pushed 2026-05-11.
- License: MIT · owner avatar + repo URL verified via GitHub API.
- README-backed entrypoint: `npx -y @steipete/peekaboo`.

## Main

- Get permissions right first: README calls out Screen Recording + Accessibility; without them, agents will fail mid-run.
- Use screenshots as evidence: capture before/after images so agent runs can be audited and reproduced.
- Prefer structured element IDs + actions (`click`, `set-value`, `perform-action`) over coordinate clicks to reduce UI flakiness.

### Source-backed notes

- README says it’s a macOS CLI and optional MCP server, exposing the same tools through both interfaces.
- README Quick start shows commands like `peekaboo image ...` and an MCP server run via `npx -y @steipete/peekaboo`.
- README lists a requirement for Screen Recording + Accessibility permissions (linked docs/permissions.md).

### FAQ

- **Do I have to use Homebrew?**: No—README also supports running the MCP server via `npx -y @steipete/peekaboo`.
- **Why are actions failing?**: Most issues are missing permissions; confirm Screen Recording + Accessibility are enabled.
- **When should I use MCP mode?**: Use MCP mode when you want agents to call tools directly from Codex/Claude Code/Cursor.

## Source & Thanks

> Source: https://github.com/openclaw/Peekaboo
> License: MIT
> GitHub: ⭐ 3986 · forks 288

Thanks to the upstream maintainers for shipping the original project.

---

<!-- ZH -->

## 快速使用

```bash
brew install steipete/tap/peekaboo
peekaboo image --mode screen --retina --path ~/Desktop/screen.png
# Or run as MCP server:
npx -y @steipete/peekaboo
```

## 简介

Peekaboo 是 macOS CLI（可选 MCP server），用于截图与点击自动化；已验证 3,986★，支持 Homebrew 安装或 `npx -y @steipete/peekaboo` 运行。

**适合谁用：** 需要“看屏幕+留证据截图+可复现 UI 操作”的 agent 工作流

**适用环境：** macOS 15+（需屏幕录制+辅助功能权限）；通过 npx 接入 MCP 客户端

**配置耗时：** 10-25 minutes

### 关键事实（已验证）

- GitHub：3986 stars · 288 forks；最近更新 2026-05-11。
- 许可证：MIT；作者头像与仓库链接均已通过 GitHub API 复核。
- README 中可对照的入口命令：`npx -y @steipete/peekaboo`。

## 正文

- 先把权限跑通：README 强调需要屏幕录制与辅助功能权限，否则 agent 会在中途失败。
- 把截图当作证据：执行前后都保存截图，便于审计与复现 agent 的操作链路。
- 优先使用结构化元素 ID 与动作（`click`/`set-value`/`perform-action`），避免坐标点击带来的不稳定。

### 基于来源的要点

- README 表示它既是 macOS CLI 也是可选 MCP server，两种方式提供同一套工具能力。
- README Quick start 给出 `peekaboo image ...` 以及用 `npx -y @steipete/peekaboo` 启动 MCP server 的示例。
- README 提示需要屏幕录制 + 辅助功能权限（见 docs/permissions.md）。

### 常见问题

- **一定要用 Homebrew 吗？**：不一定。README 也支持用 `npx -y @steipete/peekaboo` 直接运行 MCP server。
- **为什么操作失败？**：最常见是权限未开：确认屏幕录制与辅助功能权限已启用。
- **什么时候用 MCP 模式？**：当你需要从 Codex/Claude Code/Cursor 等客户端直接调用工具时，用 MCP 模式最合适。

## 来源与感谢

> Source: https://github.com/openclaw/Peekaboo
> License: MIT
> GitHub: ⭐ 3986 · forks 288


---
Source: https://tokrepo.com/en/workflows/peekaboo-macos-screenshots-clicks-mcp
Author: MCP Hub