Macbeth

Macbeth — macOS 向けオープンソースのコンピューター操作

すでにお使いのエージェントに、Mac 上の手と目を与えましょう。

MCP または TypeScript を通じて、ネイティブおよび Electron のインターフェースを含む Mac アプリケーションを確認し、操作できます。

可能な場合は構造化された UI アクセスを、必要な場合はスクリーンショットと OCR を使用します。
Mac 全体を対象にした Playwright のようなものです。

_{Macbeth の現在の MCP ツール群を示すシミュレーションウォークスルー：System Settings、Electron の操作、スクリーンショット／OCR。}

クイックスタート · 使用例 · Macbeth を選ぶ理由 · TypeScript · セキュリティ · スキル

クイックスタート

Claude Code から Macbeth にアクセスできるようにします。

claude mcp add macbeth -- npx -y macbeth

次に、接続を確認するよう依頼します。

Macbeth を使って、実行中のアプリケーションを一覧表示し、Finder に接続して、その前面ウィンドウを調べ、表示されている最初のいくつかのコントロールを要約してください。それ以外の操作は実行しないでください。

Macbeth には、ビルド済みで署名・公証済みのユニバーサルデーモンが付属しています。Swift ツールチェーンやサービスの手動インストールは必要ありません。セットアップに失敗した場合は、npx macbeth doctor を実行してください。エージェントに貼り付けられる、自己完結型の診断プロンプトが出力されます。

stdio サーバーを起動できる MCP クライアントであれば、npx -y macbeth を利用できます。一般的な設定、更新方法、ツール一覧については、MCP のセットアップをご覧ください。

エージェントにインストールを案内してもらう

npx -y macbeth を使って Macbeth を MCP サーバーとして追加してください。npx macbeth doctor を実行し、必要な権限だけを付与できるよう案内して、Finder を調べてセットアップを確認してください。関係のない操作は実行しないでください。

Mac 全体で使う

Unity、Logic Pro などの複雑なツールで作業する

「Logic Pro で、プロジェクトのテンポを 128 BPM に設定して再生を開始してください。」

Macbeth は、構造化されたコントロール、メニュー、キーボード入力、スクリーンショット、OCR、アプリケーション固有のガイダンスを組み合わせます。Logic Pro には専用スキルがあります。Unity の一部など、アクセシビリティツリーが十分でないアプリケーションでは、構造化されたコントロールに加えて、キーボード、メニュー、スクリーンショット、OCR によるフォールバックを組み合わせられます。

macOS 自体を自動化する

「System Settings を開いてファイアウォールのコントロールを見つけ、何も変更せずに現在の状態を報告してください。」

Macbeth は、名前の付いたコントロールや値を調べたり、ネイティブのメニュー項目を選択したり、セマンティックな操作が利用できない場合にキーボード入力を使用したりできます。

API がないアプリケーションも使う

「HEY を開いて、デザインチームから届いた最新の表示中のスレッドを見つけ、送信や変更はせずに要約してください。」

サービスがエージェントに必要な API を提供していない場合でも、Macbeth は公開されている Electron インターフェースを通じて操作できます。HEY は Macbeth の汎用的な Electron サポートで動作します。結果はアプリケーションのアクセシビリティツリーとバージョンによって異なります。

アクセシビリティツリーに表示されない情報を確認する

「最前面のメモウインドウをキャプチャし、表示されているテキストをすべて抽出してください。」

ScreenCaptureKit のスクリーンショットとローカルの Vision OCR により、macOS が有用なアクセシビリティデータとして公開しないコンテンツを補完できます。

再現可能なスクリプトとテストを作成する

同じエンジンは、遅延評価ロケーター、自動待機アクション、明示的な状態待機、スクリーンショット、アプリケーション接続に対応した TypeScript API としても利用できます。

重要

Macbeth はユーザーに代わってアプリケーション内で操作できます。信頼できるエージェントのみを接続し、重大な結果を伴う操作には承認を必須にしてください。

なぜ Macbeth なのか？

• 独自のエージェントを使用できます。 Macbeth は制御レイヤーであり、モデルでもエージェントランタイムでもありません。
• 可能な場合は構造化データを使用します。 座標だけに頼らず、ロール、ラベル、値、有効状態、階層、安定したハンドルを照会します。
• 必要に応じて視覚情報を使用します。 アクセシビリティメタデータが不十分な場合は、ウインドウキャプチャと OCR に切り替えます。
• アプリケーションを認識します。 バージョン管理されたスキルに、ワークフロー、ショートカット、既知の失敗パターンを保持します。
• スクリプトから利用できます。 MCP 経由で対話的に、または TypeScript から直接、同じ基本機能を使用できます。

ピクセルより先に構造化データを使用する

機能	一般的なスクリーンショット駆動のエージェント	Macbeth
ラベル付きコントロールを見つける	視覚的な推論	公開されている場合はアクセシビリティクエリ
ロール、値、状態を読み取る	推定	構造化属性
UI の変更を待つ	通常はキャプチャを繰り返して確認	明示的な待機と自動待機アクション
不完全な UI メタデータに対応する	Vision/OCR	まずアクセシビリティ情報を使用し、必要に応じてスクリーンショット/OCR に切り替え
アプリケーションの知識を再利用する	プロンプトに依存	同梱されたバージョン管理済みスキル

アクセシビリティ情報自体が不完全だったり、誤解を招いたりする場合もあります。Macbeth はハイブリッドなインターフェースです。macOS がより確かな構造化プリミティブを公開している場合はそれを使用し、公開していない場合は視覚情報やシステムレベルのフォールバックも利用できます。

セキュリティと制限事項

• Macbeth には macOS 14 以降と Node.js 20 以降が必要です。
• UI の検査と操作にはアクセシビリティの許可が必要です。スクリーンショットとウインドウ OCR に限り、画面収録の許可が必要です。
• アプリケーションによってアクセシビリティの品質は異なります。独自に描画されたキャンバス、ゲーム、一部のクリエイティブツールでは、メニュー、スクリーンショット、OCR、キーボード入力、またはアプリケーション固有のガイダンスが必要になる場合があります。
• アプリケーションのバージョン間でインターフェースが変更されると、特化したワークフローが動作しなくなることがあります。
• 操作中のグローにより Macbeth の動作を確認できますが、これは承認システムでも完全な監査ログでもありません。
• エージェントが誤操作をすることがあります。破壊的、金銭的、公開を伴う、またはプライバシーに関わる操作では、人による確認を行ってください。

Macbeth はローカルの stdio MCP サーバーと Unix ドメインソケットを使用し、TCP リスナーは開きません。MCP 経由で要求されたスクリーンショットは一時ディレクトリに書き込まれ、自動的には削除されません。データフロー、許可の取り消し、ローカルプロセスのリスク、より安全な運用方法については、セキュリティモデルをお読みください。

TypeScript API

npm install macbeth

import { connect } from "macbeth";

const app = await connect("TextEdit");
await app.window("Untitled").textField().fill("Hello from Macbeth");
await app.pressKey("s", ["cmd"]);

ロケーター、スクリーンショット、Electron の動作、ライフサイクル、テストについては、Macbeth を使った開発をご覧ください。

Macbeth にアプリケーションを教える

Macbeth のスキルは、任意で実行可能なスクリプトを伴う SKILL.md ファイルです。エージェントに信頼できるワークフローと注意点を教えます。引数なしで load_skill を呼び出すと、Macbeth のコアガイドが読み込まれます。同梱されているアプリケーションスキルは、カレンダー、連絡先、Logic Pro、メール、マップ、メッセージ、ミュージック、メモ、リマインダー、Safari、システム設定、および汎用的な Electron アプリケーションに対応しています。

Swift デーモンを変更せずにスキルを追加できます。コントリビューションガイドを参考に、再現可能なプロンプト、テスト済みのアプリケーションバージョン、期待される結果、実際に確認された失敗パターンを記載してください。

ドキュメント

ガイド	内容
MCP サーバー	インストール、スモークテスト、ツール、スキル、アップデート
CLI	すべての MCP ツールを macbeth <tool> サブコマンドとして利用
TypeScript API	クライアント API、ロケーター、Electron、テスト
アーキテクチャ	デーモン、プロトコル、フォールバック、設計メモ
セキュリティ	信頼境界、データ処理、権限の取り消し
トラブルシューティング	診断とよくあるセットアップの問題
コントリビューション	開発ワークフローとアプリケーションスキル

要件

• macOS 14（Sonoma）以降
• Node.js 20+
• デーモンをソースからビルドする場合のみ Swift 6.0+

ライセンス

MIT