Peekaboo MCP – lightning-fast macOS screenshots for AI agents

Peekaboo 🫣 — 画面を見てクリックする、Mac 自動化ツールです。

Peekaboo は、画面キャプチャ、アクセシビリティの調査、ネイティブ UI の自動操作に対応した macOS 向けの CLI とメニューバーアプリです。直接使うことも、エージェントに複数ステップの作業を計画させることも、同じツールセットを MCP クライアントに公開することもできます。

インストール

リリース版の CLI とアプリには macOS 15 以降が必要です。

Homebrew で CLI をインストール

brew install openclaw/tap/peekaboo

npm で MCP パッケージをインストール

npm パッケージには Node.js 22 以降が必要です。CLI と MCP ランチャーが含まれています。

npx -y @steipete/peekaboo --version

Codex、Claude Code、Cursor、またはその他の MCP クライアントへの接続については、MCP のセットアップをご覧ください。

Mac アプリ

署名済み DMG を最新の GitHub リリースからダウンロードしてください。メニューバーアプリには、権限の初期設定、視覚的なフィードバック、エージェントセッションの機能があります。PATH 上でも peekaboo を使う場合は、CLI を別途インストールしてください。

ソースからのビルド方法やその他のインストール方法については、インストールガイドをご覧ください。

クイックスタート

Peekaboo で利用できる権限を確認してから、スクリーンショットを撮影します。

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

画面キャプチャには画面収録の権限が必要です。アクセシビリティの権限を許可すると、UI の調査と操作が可能になります。権限ガイドでは、セットアップ方法と、合成入力に必要な追加の権限について説明しています。

実行中のアプリを調査し、識別子が不透明な UI 要素を含む構造化マップを取得します。

peekaboo see --app Finder --json

これが基本的な流れです。現在の画面を確認し、結果から要素を選んで操作します。

バージョン 4.9.7 の新機能

Peekaboo 4.9.7 は修正リリースです。デーモン経由の window close は、アプリが閉じたウィンドウを残していても成功を報告するようになりました。see は、タイトルにアプリ名が含まれるか省略表示されている Chrome ウィンドウでも動作します。window close --foreground は、自らを再実行するアプリに対応しました。また、dock list では区切り線が非表示になります。Mac アプリでは、チャット中に次の質問をキューに入れてもストリーミング中の回答が分割されず、失敗したツールは失敗として表示されます。プロバイダーが Vision に対応していないと通知していても、保存済みの 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、座標、スナップショット、待機、入力の動作については、自動化ガイドをご覧ください。

エージェントと MCP

エージェントは、同じ観察ツールとアクションツールを組み合わせて、自然言語による実行を行います。

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

エージェントを実行するには、モデルプロバイダーの設定が必要です。プロバイダーとセッションについてはエージェントのセットアップをご覧ください。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	エージェント · キャプチャ
クライアントと連携する	mcp, browser, tools	MCP

CLI の最新のヘルプを表示するには、peekaboo help <command> を実行してください。コマンドの完全な一覧から、すべてのコマンドのフラグ、例、トラブルシューティングを確認できます。

設定

Peekaboo は、プロバイダーの認証情報と設定を ~/.peekaboo に保存します。確認または変更するには peekaboo config を使用してください。プロファイル、環境変数、カスタムプロバイダーについては、設定ガイドをご覧ください。プロバイダーリファレンスでは、ホスト型、互換型、ローカルのモデルバックエンドについて説明しています。

zsh、bash、fish 用のシェル補完は peekaboo completions から利用できます。永続的な設定方法については、補完ガイドをご覧ください。

詳細情報

• プロジェクトの方針
• プラットフォームのサポート
• アーキテクチャ
• ソースからのビルド
• テスト
• エージェントのチャットループ
• コマンドリファレンス

コミュニティ

• PeekabooWin — @FelixKruger による、Peekaboo の自動化ループを Windows 向けに書き直したプロジェクト（JavaScript + PowerShell）
• PeekabooX — @nordbyte による、Peekaboo の自動化ループを Linux 向けに書き直したプロジェクト（Rust + Python）

開発

ソースからビルドするには、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をご覧ください。