スクリーンショットやスキャンPDFの文字を、クラウドAPIに送らずに取り出したい場面は多いです。
この記事では、AppleのVision Frameworkを使ってMac上だけでOCRできるCLIツール「mac-ocr」の使い方と、開発者・AIエージェント運用で役立つポイントを整理します。
この記事でわかること
- mac-ocrが解決する課題と仕組み
npx mac-ocrですぐ試せる基本コマンド- 検索可能PDFの作成やJSON出力などの応用
- 類似ツールとの違いと向いている用途
https://github.com/privatenumber/mac-ocr
画像内テキストを取り出す手間とプライバシーの壁
レシートの数字を転記したり、スキャン文書を検索可能にしたりするには、画像から文字を抜き出す必要があります。従来はクラウドOCRサービスに画像を送る方法が一般的でした。
クラウドOCRは手軽ですが、社内資料や個人情報を含む書類では外部送信が問題になります。API利用料もファイル数に比例して積み上がります。さらにAIエージェントに画像を渡して読ませると、vision tokenを大量に消費します。
mac-ocrは、この課題を「Mac内で完結するOCR」で解きます。2026年6月13日にv1.0.0が公開され、開発者のHiroki Osame氏（GitHub: privatenumber）がXでも紹介しています。
mac-ocrとは何か
mac-ocrは、macOS向けのOCR用CLIツールです。内部ではSwift製のネイティブバイナリがAppleのVision Framework（VNRecognizeTextRequest）を呼び出し、画像やPDFから文字を認識します。認識処理はすべてデバイス上で行われ、画像データは外部にアップロードされません。
npmパッケージとして配布されており、依存パッケージはゼロです。macOS 10.15以降に対応し、プリビルド済みのユニバーサルバイナリが同梱されるため、XcodeやSwiftの開発環境は不要です。ライセンスはMITです。
すぐ試せる基本の使い方
インストールせずに試すなら、次の1行で画像内テキストを標準出力に出せます。
npx mac-ocr ./image.png
グローバルインストールする場合は npm install -g mac-ocr です。コマンド名だけでOCRが走るため、サブコマンドは不要です。
mac-ocr receipt.jpg
mac-ocr page1.png page2.png
mac-ocr scan.pdf
cat screenshot.png | mac-ocr
PDFはページ単位で認識され、大きな文書でも先頭ページから順に結果が出ます。URLを直接渡す簡易GETにも対応しています。
主な機能
テキスト・JSON・JSONLの出力
デフォルトはプレーンテキストです。座標や信頼度が必要なら --format json を使います。複数ページのPDFを1ページずつストリーム出力する場合は --format jsonl が向いています。
検索可能PDFの作成
searchable-pdf サブコマンドで、見た目はそのままに選択・検索できるテキスト層を重ねたPDFを作れます。
mac-ocr searchable-pdf scan.pdf
mac-ocr searchable-pdf photo.jpg
出力はデフォルトで 元ファイル名.ocr.pdf です。すでにテキスト層があるページはスキップされ、スキャン画像だけにOCRがかかります。
バッチ処理とファイル保存
複数ファイルの一括処理や、-o による出力先指定に対応しています。テンプレート [dir]/[name].txt を使えば、スクリーンショットフォルダ内の画像をまとめてテキスト化し、grep で検索する運用も組めます。
言語・精度の調整
-l en-US -l ja-JP のようにBCP-47形式で認識言語を指定できます。--fast で高速モード、--confidence で低信頼度の結果を除外するなど、用途に合わせた調整が可能です。暗号化PDFには --password を渡せます。
Node.js APIとエージェント連携
同じパッケージから ocr や createSearchablePdf などのPromiseベースAPIも使えます。画像やPDFのバイト列を渡す設計です。
READMEでは、AIエージェントに画像を渡してvision tokenを消費する代わりに、ローカルで mac-ocr を実行してテキストだけ渡す運用が推奨されています。Agent Skills形式のスキルファイルも同梱されており、skills-npm を導入したプロジェクトではコーディングエージェントが自動で使い方を参照できます。
料金
mac-ocr自体はMITライセンスのオープンソースで、利用料はかかりません。Apple Vision FrameworkはmacOSに組み込まれた機能を使うため、OCRのたびにクラウドAPI料金が発生することもありません。必要なのはmacOS 10.15以降のMacとNode.jsの実行環境だけです。
類似ツールとの違い
macOS向けのVision Frameworkラッパーは他にもあります。macos-vision はOCRに加えて顔検出・バーコード読み取り・画像分類など、Vision Frameworkの複数機能を1つのCLIで扱えます。macos-vision-mcp はMCPサーバーとしてClaude CodeやCursorから呼び出す構成です。
mac-ocrの強みは、OCRと検索可能PDF作成に特化したCLI設計にあります。stdin・URL入力・JSONLストリーム・暗号化PDF対応・エージェント向けスキル同梱など、文書処理パイプラインに組み込みやすい機能が揃っています。顔検出や画像分類まで1ツールで済ませたい場合は macos-vision 系の方が向いています。
向いている人と注意点
画像内テキストの抽出、スキャンPDFのテキスト化、AIエージェントへの文書渡しをローカルで完結させたい開発者に向いています。macOS専用である点は前提として覚えておいてください。LinuxやWindowsでは動作しません。
まずは手元のPNGやJPEGで npx mac-ocr ./image.png を試し、必要に応じて --format json や searchable-pdf を組み合わせるのがおすすめです。