macos-vision-mcp

macos-vision-mcp

_{書類と画面はマシン上にとどまります。モデルに送られるのは、抽出されたテキストと構造化 JSON だけです。}

あらゆる MCP クライアントで使える、ローカルでプライベート、オフライン対応の OCR および UI テストです。API キーもアップロードも不要です。 書類のトークンコストを約 97% 削減し、スクリーンショットをマシンの外に一切送ることなく、エージェントが Mac の UI を見てクリックできるようにします。

AI がデータを見る前に、テキストと画像データをローカルで事前抽出します。実際の書類でトークン使用量を約 97% 削減し、構造化された段落、行、バウンディングボックスを返すため、モデルは書類を Markdown、HTML、DOCX、その他の形式に再構成できます。ファイルが Mac の外に出ることはありません。クラウド API、API キー、ネットワークリクエストは不要です。

_{約 97% の測定方法： 44 ページのスキャン済み PDF をページ画像として送ると約 73,500 トークンかかります。同じファイルを analyze_document で処理すると、抽出されたテキストと構造は約 2,400 トークンになります（ページ画像の生トークン数と抽出テキストのトークン数の比較）。数値はページの密度やトークナイザーによって変わるため、97% は保証値ではなく、おおよその目安としてお考えください。}

目次： クイックスタート · 得られるもの · エージェントの活用方法 · UI テスト · 他との違い · 利用可能なツール · 使い方 · ワークフローの例 · 設定 · プライバシーレイヤー

得られるもの

• Apple Vision Framework による画像と PDF（JPG、PNG、HEIC、TIFF、複数ページの PDF）の OCR。
• トークンを約 97％削減：44 ページの PDF のコストは約 73,500 トークンではなく、約 2,400 トークンです。
• 読み取り順の段落と、バウンディングボックス付きの未加工テキストブロックを提供します。モデルがドキュメントを任意の出力形式（Markdown、HTML、DOCX、JSON）に再構成できる豊富な構造であり、情報が失われるプレーンテキストの出力ではありません。
• 顔検出、バーコード／QR コード読み取り、画像分類をすべてデバイス上で実行します。
• ドキュメント処理の完全なパイプライン：OCR、顔、バーコード、四角形の検出を 1 回のツール呼び出しで実行します。
• Claude Code、Claude Desktop、Cursor など、MCP 対応クライアントで動作します。
• ファイルがサーバーにアップロードされることはありません。処理はすべて Mac 上で行われます。
• エージェント向け UI テスト：ウィンドウのスクリーンショットをローカルで取得し、表示されているテキストから要素を見つけ、クリック座標を取得して、画面に表示されている内容をアサートできます。スクリーンショットのアップロードは不要です。
• Apple Vision Framework を利用しているため、npm install 後は 100％オフラインで動作します。Photos.app の Live Text と同じエンジンです。

❌ なしの場合／✅ ありの場合

❌ macos-vision-mcp がない場合：

• 44 ページの PDF の送信に約 73,500 トークンかかります
• 画像、請求書、契約書はすべてクラウド API を経由します
• リクエストのたびに機密文書がマシンの外部に送信されます

✅ macos-vision-mcp がある場合：

• ローカルの Apple Vision がテキストを事前に抽出するため、Claude が内容を見る前に処理できます
• 同じ 44 ページの PDF でも約 2,400 トークンで済み、97％削減できます
• ファイルが Mac の外部に出ることはありません

エージェントの活用例

Mac 上でエージェントが行う作業のほとんどは、レイアウトを深く理解する必要はありません。画面に何が表示されているかを確認し、探しているものを見つけ、操作して、結果を確かめる必要があります。この一連の流れである list_windows → find_element → クリック（任意の入力ドライバーを使用）→ assert_text は多くの作業に対応し、そのすべてのステップがマシン上で実行されます。

• API のないアプリを操作する。 ネイティブツール、Electron アプリ、社内ソフトウェアなど、GUI はあってもスクリプト用のインターフェースがないものに対応します。find_element("Export") はクリックする位置を返します。
• 今、画面に表示されている内容を読み取る。 ダイアログ、エラーバナー、通知、進行状況など、ほかのウィンドウの背後にあるウィンドウも前面に出さずに読み取れます。
• 操作が実際に成功したことを確認する。 assert_text は Unicode 正規化後に文字列を照合するため、モデルに画像を判定させる代わりに、毎回同じ方法で成功か失敗かを返します。
• エクスポートできないソフトウェアからデータを取り出す。 ウィンドウを OCR で読み取り、テキストを取得したら次に進みます。
• アクセシビリティを監査する。 ui_snapshot は、アクセシビリティツリーで認識されていない表示テキストをすべて報告します。ラベルのないコントロールやカスタム描画されたテキストも、座標とともに確認できます。
• UI のリグレッションをテストする。 このプロジェクトの出発点となった用途であり、現在も有効な活用例です。下の章をご覧ください。
• ドキュメントを処理する。 当初の用途である、請求書、契約書、スキャン、PDF の処理です。

ローカルで実行するほうが、単に違うだけでなく優れている理由

コストを抑えられます。 判定にかかるのは約240トークンで、置き換えるスクリーンショットの約6,900トークンに対して、約29分の1です。20ステップのタスクなら、約138,000トークンではなく約4,800トークンで済みます。各ステップの後に作業を確認する余裕のあるエージェントと、それができないエージェントの違いです。

プライバシーがより守られます。しかも、請求書には決して表れない部分です。 スクリーンショットは、気になるボタンだけをきれいに切り抜いたものではありません。別のウィンドウやパスワードマネージャー、開いたままの受信トレイ、顧客の記録など、画面に表示されているほかのものも写り込みます。スクリーンショットを第三者に送ると、取り消せない情報開示が発生し、それが各ステップで繰り返されます。ここでは画像を一時ファイルに書き込み、Neural Engine 上のモデルが読み取ります。会話にシリアライズされることはありません。この不変条件は README で約束しているのではなく、コードによって保証されています。どのツールも画像バイト列を返しません。

実際の利用ではより高速で、しかも予測可能です。こちらのほうが重要です。 find_element のエンドツーエンドの処理時間は M1 Pro で1.17～1.25秒です。キャプチャに0.31～0.41秒、OCR に約1.04秒かかり、マッチングは1ミリ秒未満です。ネットワークにかかる時間は一切ありません。推論を開始する前の約750 KBのアップロードも、レート制限も、高負荷状態のプロバイダーも、Wi-Fi が切れたときの失敗もありません。同じ呼び出しなら、飛行機の中でもデスクでも同じ時間で処理できます。

これはクリックしません。 これは目であり、手ではありません。そのため、マシンの操作権限を求めることはありません。入力ドライバー（cliclick、macos-mcpのような自動化サーバー、または画面座標を受け取るもの）と組み合わせて、find_element が返す clickPoint を渡してください。この分離は意図的なものです。見ることと操作することは異なる権限であり、このサーバーが求めるのは前者だけです。

スクリーンショットをどこにも送信しない UI テスト

エージェントに GUI を操作させる一般的な方法は、画面のスクリーンショットを撮り、ビジョンモデルにアップロードすることです。各ステップで、ネットワークとの往復が1回、画像トークンの料金が1回、画面に表示されているもののコピーが1つ発生します。10ステップのフローなら、デスクトップを10回アップロードすることになります。

このサーバーはローカルで画面を認識します。Apple の Vision フレームワークが Neural Engine 上で動作するため、スクリーンショットはディスク上に残り、モデルに届くのはテキスト、位置や形状の情報、判定結果だけです。

_{エージェントが実際に受け取る情報。計測された要素の枠、役割、ラベル。推測ではありません。また、クリックする正確な位置も含まれます。スクリーンショット自体が Mac の外に出ることはありません。}

find_element(query: "Save", app: "MyApp")
  → { found: true, matches: [{ text: "Save", method: "exact",
        clickPoint: { x: 812, y: 556 }, bbox: {...} }] }

# hand clickPoint to any input driver — macos-mcp, cliclick, CGEvent
# then verify, again locally:

assert_text(expect: "Saved", app: "MyApp")  → { pass: true, ... }

clickPoint は左上を原点とするグローバル画面ポイントで表されます。クリックドライバーが使う座標系と同じなので、変換せずにそのままドライバーに渡せます。このサーバーは意図的にクリックしません。これは目であり、手ではありません。そのため、マシンの操作権限を求めることはありません。

実際に、より安く、安全で、速いのでしょうか？

**Apple M1 Pro（2021年、16 GB）**で、実際のテキスト量が多いアプリの2992×1734 Retinaウィンドウキャプチャを使って測定しました。各5回の実行の中央値です。

	ローカル（このサーバー）	スクリーンショット → クラウドビジョン API
ステップあたりのトークン数	約240（assert_text の判定）	約6,900（2992×1734の画像トークン）
Macから外部に送信されるデータ	なし	ステップごとに約750 KBのPNG画像
ネットワーク	なし — オフライン、飛行機内、エアギャップ環境でも動作します	ステップごとに1回の往復
レイテンシ	find_element のエンドツーエンドで1.17～1.25秒	アップロード＋推論＋応答
コスト	$0	画像ごと、ステップごと、ずっと発生

_{画像トークン数は、Anthropicの幅 × 高さ / 750というルールに基づく推定値です。他のプロバイダーでは異なる方法で分割されるため、正確な数値は変わりますが、桁は変わりません。ローカルのトークン数は、ツールが返した実際のJSONペイロードを、約4文字を1トークンとして数えたものです。}

_{同じ質問、同じ回答、価格は約29倍。 M1 Proで2992×1734のウィンドウキャプチャを使って測定しました。}

この表の3つの主張、つまり「より安い」「より安全」「より速い」については、上記のエージェントの利用例で説明しています。このセクションでは測定結果を示します。数値は、実際のテキスト量が多いウィンドウの2992×1734 Retinaキャプチャを使い、Apple M1 Pro（2021年、16 GB）で5回実行した中央値です。

特定のビジョンプロバイダーのベンチマークは実施していないため、右側の列は実測値ではなく、構造を示すものとしてご覧ください。ローカルでの処理には、帯域幅、レート制限、プロバイダーの負荷による変動がなく、ネットワーク障害時にも失敗しないことは明言できます。

正直にお伝えすべき注意点が2つあります。ウィンドウ全体ではなく単一の領域を対象にすると、検索対象のピクセル数に応じてコストが変わるため、OCRのコストを大幅に削減できます。また、インストール後の最初の呼び出しでは、小さなSwiftヘルパーのコンパイルに約2秒かかります。それ以降の呼び出しはすべてウォーム状態です。

得意なことと、そうでないこと

得意なこと：ネイティブの macOS アプリ、アクセシビリティ対応が不十分な Electron アプリ、キャンバス／WebGL の UI、ゲーム、デザインモックアップなど、DOM を照会できないものです。また、モデルの意見ではなく決定論的なアサーションが必要な場合にも適しています。assert_text は Unicode 正規化後に文字列を照合するため、毎回同じ結果を返します。

一般的なウェブページには適したツールではありません。その場合は Playwright または DOM のほうが高速で正確です。また、OCR で確認できるのはレンダリングされた内容のみなので、コントロールの enabled 状態やアクセシビリティのロールは読み取れません。

比較の前にテキストを正規化します。NFC、空白の連続の圧縮、Unicode のダッシュと引用符の統一を行ったうえで、完全一致 → 部分文字列一致 → あいまい一致（Levenshtein）の順に試します。一致が却下された場合も nearMisses に報告されるため、「ラベルはあるが、OCR が Zapisz を Zapisr と読み取った」のか、「ラベルが実際に存在しない」のかを区別できます。

部分文字列の一致は一律に扱わず、スコアで評価します。単語の境界に沿い、ラベルの先頭から始まり、ラベルのより広い範囲を含むクエリほど高いスコアになります。答えがボタンの場合、この順序が重要です。クエリが Save なら、Save Changes は Don't Save より上位になる必要があります。一致ごとに wholeWord が報告され、assert_text はこの値が true の一致のみで判定します。Unsaved changes 内の Save はつづりが偶然一致しているだけで、Save ボタンが画面にあることも、ないことも証明しません。このような一致も incidental に記載されます。

要件

• MCP サーバーをホストするアプリ（Terminal、Claude Desktop、Cursor）に画面収録のアクセス許可が必要です。「システム設定」→「プライバシーとセキュリティ」→「画面収録」の順に開き、アプリを再起動してください。コンパイラや Xcode のツールは不要です。ネイティブヘルパーはビルド済みの状態で提供されます。

  許可はパッケージ単位ではなく、ホストプロセス単位で付与されます。同じ Mac でも、あるクライアントではサーバーが完全に動作し、別のクライアントでは画面を確認できないことがあります。許可がない場合、キャプチャは完全に失敗し、macOS はすべてのウィンドウタイトルも提供しません。そのため、list_windows はすべてのウィンドウについて title: "" を報告します。この状態は、タイトルのないウィンドウが並ぶ画面のように見えないよう、titlesAvailable: false として示されます。まず vision_capabilities を実行してください。ready と blockers で、現在動作する機能を確認できます。

• Mac のロックが解除されていること。ロック中のマシンでは、ウィンドウキャプチャと領域キャプチャは完全に失敗し、全画面キャプチャではロック画面のみが返されます。vision_capabilities は screenLocked を報告するため、エージェントは失敗の後で推測するのではなく、処理を開始する前に確認できます。

違い

LLM 向けの OCR オプションの多くは、ドキュメントをクラウドの Vision API に送信するか、独自のエンジンを構築して調整する必要があります。このツールは、Apple のオンデバイス Vision フレームワーク（Photos.app の Live Text と同じエンジン）上で動作するため、抽出は無料で、プライベートに保たれ、瞬時に完了します。

	macos-vision-mcp	クラウド Vision OCR（GPT-4o、Google Vision、Mistral OCR）	Tesseract ベースの MCP
コスト	$0 — ページ単位またはトークン単位の料金はありません	呼び出しごと／ページごとの課金	$0。ただしセルフホストが必要
オフライン	インストール後は可能	不可 — すべてのページでネットワークに接続	可能
プライバシー	ファイルが Mac の外に出ることはありません	ドキュメントが第三者にアップロードされます	ローカル
セットアップ	コマンド 1 つ。キーは不要	API キーと課金アカウントが必要	インストール＋言語データ＋調整
品質	Apple Vision（鮮明なスキャン、レシート、スクリーンショットに強い）	一般に高品質	ばらつきがあります。低品質なスキャンでは精度が落ちます
UI テスト	組み込み — キャプチャ、位置特定、アサーションが可能。アップロードは不要	可能ですが、手順ごとに画面をアップロードします	OCR のみ。キャプチャや対象指定はできません

トレードオフについては正直にお伝えします。macOS 専用であり、大きく傾いているスキャンやコントラストの低いスキャンでは、クラウドモデルのほうが多く読み取れる場合があります。一般的な用途（請求書、契約書、レシート、スクリーンショット、鮮明な PDF）では、コストもセットアップもゼロで、マシンの外に何も送信せずに、クラウド級の抽出を利用できます。

プライバシーレイヤー

macos-vision-mcp は、ドキュメントとクラウドの間でローカルの前処理レイヤーとして機能します。次のような用途に役立ちます。

• 法的文書、契約書、NDA
• 財務報告書、請求書、社内のスプレッドシート
• 医療記録や、GDPR の配慮が必要なあらゆるコンテンツ
• クラウドに送信する内容（または送信するかどうか）を判断する前に、構造化データをローカルで抽出したい場合

生のドキュメントを AI に送信する代わりに、まずテキストと構造をローカルで抽出します。その後、モデルは抽出されたテキストだけを扱い、元のファイルにはアクセスしません。

画面にも同じことが当てはまります。ちょっとした確認のために撮ったスクリーンショットにも、ほかのウィンドウ、パスワードマネージャー、顧客情報、開いた受信トレイなど、画面に表示されていたものがすべて含まれています。UI テスト用ツールは、その画像をディスク上に保持し、パス、座標、テキストのみを返すため、UI アサーションによって意図しない情報開示が起こることはありません。このサーバーのどのツールも、画像のバイト列をモデルに返しません。

クイックスタート

MCP クライアントに追加します（Claude Code の例）：

claude mcp add macos-vision-mcp -- npx -y macos-vision-mcp

Claude Desktop または Cursor をお使いですか？ 設定へ移動 ↓

クライアントを再起動してください。初回実行時に npx がパッケージを取得してキャッシュするため、別途インストールしなくてもツールが自動的に表示されます。これはほとんどの MCP サーバーで採用されている慣例であり、Anthropic、Cursor などのクライアントが推奨しています。

注： 初回実行時、パッケージはビルド済みの Swift ヘルパーバイナリ（vision-helper、pdf-helper、ui-helper、ax-helper）を GitHub Releases からダウンロードします（圧縮時約 276 KB、約 1～2 秒）。2 回目以降の実行では npx のキャッシュが使われ、すぐに起動します。ダウンロード時にネットワークへ接続できない場合のフォールバックとしてのみ、Xcode Command Line Tools が必要です。MACOS_VISION_SKIP_DOWNLOAD=1 を設定すると、swiftc でローカルコンパイルを強制できます。

**起動時の待ち時間をなくしたい場合（npx のキャッシュ確認なし）**は、npm install -g macos-vision-mcp でグローバルにインストールし、設定の最後にある代替設定を使用してください。

利用可能なツール

ツール	機能	プロンプトの例
ocr_image	画像または PDF（JPG、PNG、HEIC、TIFF、PDF）からテキストを抽出します。プレーンテキスト、または lineId / paragraphId とバウンディングボックスを含むページごとの段落とテキストブロックを返します。部分的な PDF OCR には start_page / max_pages を指定できます。	「~/Desktop/screenshot.png からテキストを読み取って」
detect_faces	人の顔を検出し、その数と位置を返します。	「この写真には何人写っていますか？」
detect_barcodes	QR コード、EAN、UPC、Code128、PDF417、Aztec、その他の 1D/2D コードを読み取ります。	「/tmp/qr.jpg の QR コードには何と書かれていますか？」
detect_document	写真に写った書類（用紙、レシート、ID）の四隅の座標を検出します。OCR の前処理として、切り抜きや傾き補正の目安に役立ちます。	「~/Desktop/receipt.jpg の書類の四隅を見つけて」
classify_image	画像の内容を 1000 以上のカテゴリに分類し、信頼度スコアを返します。	「この画像には何が写っていますか？」
analyze_document	読み取り順の段落、テキストブロック（バウンディングボックス / 信頼度）、顔、バーコード、矩形を含む構造化 JSON を返します。モデルが Markdown、HTML などに再構成できる形式です。長い PDF では start_page / max_pages も指定できます。	「~/Desktop/scan.pdf を整った Markdown に再構成して」

UI テスト用ツール（ローカルで実行し、スクリーンショットをクラウドに送信しません）

これらのツールを使うと、エージェントはスクリーンショットをクラウドモデルに送信することなく、Mac の UI を確認して検証できます。スクリーンショットはローカルでキャプチャされ、OCR はデバイス上で実行され、返されるのはパス、座標、抽出されたテキストのみです。find_element は画面上の座標でクリック位置を返すため、任意の入力ドライバーにそのまま渡せます（このサーバーは意図的にクリックしません。目で確認し、手は動かしません）。

ツール	機能	プロンプトの例
capture_screen	メインディスプレイ、ウィンドウ（ほかのウィンドウに隠れているものも含む）、アプリの最前面のウィンドウ、または指定領域のスクリーンショットを撮影します。ファイルパスと画面上の座標で示すフレームを返します。画像データは返しません。	「Safari のウィンドウをキャプチャして」
list_windows	画面上のウィンドウを、グローバルな画面座標で示す境界情報とともに、前面から背面の順に一覧表示します。	「開いているウィンドウは何ですか？」
read_screen_text	キャプチャと OCR を一度に行い、アプリに現在表示されている内容を完全オフラインで読み取ります。	「TestFlight のウィンドウには何と表示されていますか？」
find_element	表示テキストで UI 要素を検索し、グローバルな画面座標の clickPoint {x,y} を返します（完全一致 → 部分一致 → あいまい一致の順に検索し、近似候補も報告します）。	「MyApp の保存ボタンはどこですか？」
assert_text	画面上にテキストがあるかどうかをローカルで合否判定します。判定はクラウドモデルではなく、Mac 上で行われます。	「保存をクリックした後、ダイアログに『保存しました』と表示されることを確認して」
vision_capabilities	macOS のバージョン、画面収録／アクセシビリティの許可状態、ディスプレイを報告します。	「このマシンで UI テストを実行できますか？」
ui_snapshot	レイアウト全体を JSON で返します。アクセシビリティツリーから取得した各要素の正確なボックス、ロール、ラベル、状態を含み、必要に応じて色やフォントも含めます。さらに、ツリーで把握できない表示テキストも含みます。	「このダイアログのレイアウトを確認して」・「ラベルのない要素はどれですか？」

MCP サーバーをホストするアプリ（Terminal／Claude Desktop／Cursor）に画面収録の許可が必要です：システム設定 → プライバシーとセキュリティ → 画面収録を開き、その後アプリを再起動してください。ほかにインストールするものはありません。ネイティブヘルパーは macos-vision にビルド済みで同梱されています。

ui_snapshot — テキストだけでなくレイアウトも

find_element は「X はどこにありますか」に答えます。ui_snapshot は「この画面に何が表示されていますか」に答えます。各要素の測定済みのボックス（OCR から推測したものではなく、アクセシビリティ API から取得）、ロール、ラベル、有効状態、親子構造に加え、任意でキャプチャからサンプリングした色と実際のフォントデータを取得します。

{
  "app": "MyApp",
  "window": [0, 29, 1496, 867],
  "source": "ax+px",
  "budget": { "elements": 289, "walked": 400, "capped": false, "elapsedMs": 136 },
  "nodes": [
    {
      "id": 42,
      "parent": 7,
      "role": "Button",
      "label": "Zapisz",
      "box": [812, 540, 96, 32],
      "style": { "bg": "#2F6FEB", "border": "#1B4FC4", "borderWidth": 1 },
      "text": { "font": "SFPro-Semibold", "size": 13, "align": "center" },
    },
  ],
  "unresolved": [{ "text": "Sprzedaż Q4", "box": [420, 300, 88, 16], "coveredByNode": 17 }],
  "summary": {
    "nodes": 289,
    "labelled": 240,
    "ocrBlocks": 123,
    "unresolved": 21,
    "axTextCoverage": 0.83,
  },
}

unresolved は Vision が読み取れるものの、どのアクセシビリティノードにも該当しないテキストです。AX が見落とす領域（キャンバス、WebGL、ゲーム、画像に埋め込まれたテキストなど）を補完します。各エントリはアプリのアクセシビリティ上のギャップを示します。coveredByNode が存在する場合は、コントロールはあるもののラベルが付いていません。存在しない場合は、何も公開されていません。

結果は正しく読み取ってください。budget.capped はツリーが不完全であることを意味します。その場合、summary.axTextCoverage が null になるのは意図的です。上限に達した状態での走査で測定できるのは、どれだけ確認したかであり、アプリのアクセシビリティではありません。色はピクセルから取得するため、遮られた要素には、その上に描画されたものの色が報告されます。borderWidth は推定値であり、パディングやマージンはありません。これは CSS のボックスモデルではありません。

スクリーン収録に加えてアクセシビリティの許可が必要です。また、Mac のロックを解除しておく必要があります。画面がロックされていると、アクセシビリティウィンドウは一切公開されません。

使用方法

ローカル処理を確実に行うには、プロンプトでツール名を明示してください。

画像または PDF からテキストを抽出する：

Use ocr_image to extract text from ~/Desktop/invoice.pdf

写真内の顔を検出する：

Use detect_faces on ~/Photos/team.jpg and tell me how many people are in it

画像の内容を分類する：

Use classify_image on ~/Downloads/unknown.jpg

ドキュメント全体を分析して再構成する：

Use analyze_document on ~/Desktop/report.pdf and reconstruct it as clean Markdown

このツールは構造化 JSON を返します。モデルは追加の依存関係なしで、指定された出力形式（Markdown、HTML、DOCX のアウトラインなど）を選択します。Ollama、クラウド LLM、追加のツールは不要です。

ワークフローの例

サーバーに接続すれば、すぐに使える実際の組み合わせを紹介します。

• 「PDF を LLM 向けの整った Markdown に変換する」 — analyze_document は読み取り順の段落とバウンディングボックスを返します。モデルは、ドキュメントサイト、ナレッジベース、RAG パイプラインにそのまま追加できる Markdown を生成します。
• 「GPT に送信する前に請求書のデータをローカルで抽出する」 — analyze_document で PDF から明細、合計金額、販売元、日付をローカルで抽出し、構造化 JSON だけを上流に送信します。元のドキュメントが Mac の外に出ることはありません。
• 「レシートをスキャンして JSON に変換し、経費管理ツールに登録する」 — スマートフォンで撮影した写真に対して ocr_image を実行し、モデルが金額／日付／店舗名を正規化して、結果を経費管理ツールの API に直接渡します。
• 「スクリーンショットから QR コードを読み取る」 — detect_barcodes は、1 回の往復でデコードした値とシンボロジーを返します。
• 「OCR の前に紙のフォームの写真をトリミングする」 — detect_document は四隅の座標を返します。これを使って（または後続のツールに渡して）、テキストを読み取る前に画像の傾きを補正し、トリミングできます。
• 「アプリの Save ボタンをクリックする」 — find_element は画面上のポイントとして clickPoint を返します。クリックドライバー（macos-mcp、cliclick）に渡してください。スクリーンショットが Mac の外に出ることはありません。
• 「変更後もアプリが正しく表示されることを確認する」 — assert_text は画面上の内容を決定論的に合否判定します。スクリーンショットの約 6,900 トークンに対し、チェックあたり約 240 トークンで済みます。
• 「バックグラウンドにあるウィンドウのエラーメッセージを読む」 — read_screen_text は他のウィンドウの背後に隠れているウィンドウも含め、特定のウィンドウをキャプチャしてテキストだけを返します。
• 「今、アプリには何が表示されていますか」 — list_windows で対象を選び、read_screen_text で読み取ります。ウィンドウを前面に表示する必要はありません。

出力スキーマ（analyze_document）

{
  "source": { "path": "...", "pageCount": 1, "isPdf": false },
  "pages": [
    {
      "page": 0,
      // primary surface for reconstruction — reading-order paragraphs joined with "\n"
      "paragraphs": [
        { "paragraphId": 0, "lineIds": [0], "text": "ACME COFFEE" },
        { "paragraphId": 1, "lineIds": [1, 2], "text": "12 Main St\nPortland, OR" },
      ],
      // spatial fallback — raw blocks with page-local 0–1 bbox, confidence, line/paragraph membership
      "textBlocks": [
        {
          "text": "ACME COFFEE",
          "lineId": 0,
          "paragraphId": 0,
          "confidence": 0.99,
          "bbox": { "x": 0.21, "y": 0.04, "width": 0.58, "height": 0.06 },
        },
      ],
      "faces": [],
      "barcodes": [],
      "rectangles": [],
    },
  ],
  "summary": {
    "totalTextBlocks": 8,
    "totalParagraphs": 2,
    "totalFaces": 0,
    "totalBarcodes": 0,
    "totalRectangles": 0,
  },
}

95％のケースではparagraphs[].textを使用して、Markdown／HTML／プレーンテキストをそのまま再構築してください。空間的なコンテキストが必要な場合（複数列のレイアウト、表、フォーム、IDなど）はtextBlocks[]を使用してください。

注記：

• blocksモードのocr_imageは、検出セクションを除いた同じページごとの形式を返します：{ pages: [{ page, paragraphs, textBlocks }] }。
• PDFはページごとに処理されます。すべての座標はページ内の相対値（0～1）で、paragraphId／lineIdはページごとにリセットされます。
• PDFの顔、バーコード、四角形の検出はベストエフォートです。基盤となるバイナリはページごとではなくファイル全体を解析するため、返される検出結果はすべてページ0にのみ割り当てられます。
• 段落のグループ化には空間的なヒューリスティクスを使用します。複数列のレイアウト（雑誌の見開きや、サイドパネル付きのWikiページなど）では、ページ全体が単一の段落にまとめられることがあります。その場合はtextBlocks[]に切り替え、バウンディングボックスから再構築してください。

設定

以下の例では、推奨されるデフォルトのnpx -yを使用します。事前のnpm installは不要です。パッケージは初回実行時に取得されてキャッシュされ、npxのキャッシュが更新されると自動的にアップデートされます。

Claude Code

claude mcp add macos-vision-mcp -- npx -y macos-vision-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.jsonを編集します：

{
  "mcpServers": {
    "macos-vision-mcp": {
      "command": "npx",
      "args": ["-y", "macos-vision-mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.jsonに追加します：

{
  "mcpServers": {
    "macos-vision-mcp": {
      "command": "npx",
      "args": ["-y", "macos-vision-mcp"]
    }
  }
}

代替方法：グローバルインストール

コールドスタート時のnpxキャッシュの確認を省きたい場合、または特定のバージョンに固定したい場合は、一度インストールします：

npm install -g macos-vision-mcp

…その後、上記のいずれかのJSON設定で"command": "macos-vision-mcp"（argsなし）を使用するか、Claude Codeではclaude mcp add macos-vision-mcp -- macos-vision-mcpを実行します。nvm／asdf／voltaでNodeのバージョンを切り替えるとグローバルインストールが動作しなくなることがあるため、切り替え後にnpm install -gを再実行してください。

サポート

macos-vision-mcpによってトークンを節約できたり、Mac上のドキュメントを保持できたりした場合は、リポジトリにスターを付けることをご検討ください。他のユーザーが見つけやすくなります。

コントリビューション

コントリビューションを歓迎します。コミットメッセージにはConventional Commitsに従ってください。

リリースにはchangesetsを使用します。変更がユーザーに見える場合は、PRにchangesetを追加してください：

npm run changeset   # pick patch / minor / major, describe the change

masterへのマージ後、バージョン、server.json、変更履歴を更新する「version packages」PRが作成されます。そのPRをマージすると、npmへの公開（provenance付きのTrusted Publishing）、リリースへのタグ付け、MCPレジストリエントリの更新が行われます。

git clone <repo>
cd macos-vision-mcp
npm install
npm run dev   # watch mode

ライセンス

MIT — Adrian Wolczuk