EasyOCR MCP tool

EasyOCR MCP サーバー

EasyOCR ライブラリを使用して OCR 機能を提供する Model Context Protocol（MCP）サーバーです。

EasyOCR について:
EasyOCR は、JaidedAI が開発したオープンソースの光学文字認識（OCR）ライブラリです。80 以上の言語に対応し、GPU アクセラレーションを提供しており、使いやすさと高い精度で知られています。EasyOCR は画像、スキャンした文書、写真からテキストを抽出できるため、幅広い OCR タスクに適しています。詳しくは、EasyOCR GitHub リポジトリをご覧ください。

機能

• 3 つの OCR ツール：Base64、ファイル、URL から画像を処理します
• 多言語対応：動的な選択が可能で、80 以上の言語に対応しています
• 柔軟な出力：テキストのみ、または座標と信頼度を含む詳細な結果を選択できます
• パフォーマンスの最適化：リーダーをキャッシュしてパフォーマンスを向上させます
• メモリ制御：自動アンロードとリクエストごとのアンロードに対応しています
• EasyOCR のネイティブ出力：EasyOCR の元の形式で返します

インストール

GPU のセットアップ

プロジェクト環境を作成する前に、GPU の使用方法を 1 つ選択してください。

NVIDIA GPU

お使いの OS、Python バージョン、CUDA バージョンに対応する公式の PyTorch インストール選択ツールを使用してください：

• https://docs.pytorch.org/get-started/locally/

PyTorch 選択ツールを使った一般的な Windows の pip の例：

python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

インストール後、次のコマンドで確認してください：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

AMD GPU

AMD GPU のサポート状況はプラットフォームによって異なります：

• Linux および WSL：公式の ROCm / Radeon PyTorch インストールドキュメントを使用してください
• Windows ネイティブ環境：ROCm はサポートされていますが、AMD によると、ROCm スタック全体はまだ Windows でサポートされていません

公式の参考資料：

• PyTorch のローカルインストールガイド：https://docs.pytorch.org/get-started/locally/
• AMD Windows 互換性マトリックス：https://rocm.docs.amd.com/projects/radeon-ryzen/en/latest/docs/compatibility/compatibilityrad/windows/windows_compatibility.html
• AMD PyTorch インストールガイド：https://rocm.docs.amd.com/projects/radeon-ryzen/en/latest/docs/install/installrad/wsl/install-pytorch.html

このリポジトリで Windows を使用する場合、テスト済みの方法は、次の場所にある既存の ROCm 対応 PyTorch インストールを再利用することです：

C:\Users\antonio\AppData\Local\Programs\Python\Python312\python.exe

このインタープリターで、次の結果が確認されています：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(getattr(torch.version, 'hip', None))"

AMD ROCm で期待される結果の形式：

• torch.cuda.is_available() は True を返します
• torch.version.hip は None ではありません

プロジェクト環境

# Windows example used in this repo:
# C:\Users\antonio\AppData\Local\Programs\Python\Python312\python.exe
#
# Keep using uv, but create the venv from the existing Python 3.12 interpreter.
# `--system-site-packages` allows the venv to reuse packages already installed
# in that interpreter, such as an existing AMD-enabled PyTorch build.

# Create the project venv from the existing interpreter
uv venv --python C:\Users\antonio\AppData\Local\Programs\Python\Python312\python.exe --system-site-packages

# Sync this project's dependencies into the venv
uv sync

# Remove uv-installed CPU PyTorch packages so the venv falls back to the
# AMD ROCm build that already exists in Python312
uv pip uninstall torch torchvision

# Run tests through uv without re-syncing the environment
uv run --no-sync test.py
uv run --no-sync test-gpu.py

これにより、既存の Python312 インストールを使用しながら、プロジェクトでは uv を使い続けられます。--system-site-packages を指定しない場合、通常の venv からはベースインタープリターにインストール済みのパッケージを参照できません。初期セットアップ後は uv run --no-sync を使用してください。これにより、uv がロックファイルから CPU 専用の PyTorch ホイールを再インストールするのを防げます。

使用方法

利用可能なツール

1. ocr_image_base64 - Base64 エンコードされた画像を処理します
2. ocr_image_file - ディスク上の画像ファイルを処理します
3. ocr_image_url - URL から画像を処理します
4. unload_ocr_models - キャッシュされた OCR モデルをアンロードしてメモリを解放します

パラメーター

• detail：出力の詳細レベル（デフォルト：1）
  • 0：テキストのみ - ['text1', 'text2', ...]
  • 1：詳細情報 - [([[x1,y1], [x2,y2], [x3,y3], [x4,y4]], 'text', confidence), ...]
• paragraph：段落検出を有効にします（デフォルト：false）
• width_ths：結合するテキストの幅のしきい値（デフォルト：0.7）
• height_ths：結合するテキストの高さのしきい値（デフォルト：0.7）
• unload_jobdone：この OCR 呼び出しの直後にモデルをアンロードします（デフォルト：UNLOAD_JOBDONE の値）

注：言語の選択は、MCP の設定にある EASYOCR_LANGUAGES 環境変数で構成します（下記の「設定」セクションを参照してください）。

出力例

詳細レベル 1（詳細情報）：

[
    ([[189, 75], [469, 75], [469, 165], [189, 165]], '愚园路', 0.3754989504814148),
    ([[86, 80], [134, 80], [134, 128], [86, 128]], '西', 0.40452659130096436)
]

詳細レベル 0（テキストのみ）：

['愚园路', '西', '东', '315', '309', 'Yuyuan Rd.', 'W', 'E']

サーバーの実行

# Run the MCP server through uv
uv run --no-sync easyocr-mcp.py

MCP 設定例

親となる MCP アプリケーションのサーバーとして実行する場合は、メインの MCP config.json で設定できます。

Windows の例：

{
  "mcpServers": {
    "easyocr-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "X:\\path\\to\\your\\project\\easyocr-mcp",
        "run",
        "easyocr-mcp.py"
      ],
      "env": {
        "EASYOCR_LANGUAGES": "en,ch_tra,ja"
      }
    }
  }
}

Linux/macOS の例：

{
  "mcpServers": {
    "easyocr-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/project/easyocr-mcp",
        "run",
        "easyocr-mcp.py"
      ],
      "env": {
        "EASYOCR_LANGUAGES": "en,ch_tra,ja"
      }
    }
  }
}

環境変数

• EASYOCR_LANGUAGES：言語コードのカンマ区切りリスト（デフォルト：en）
  • 例：en、en,ch_sim、ja,ko,en
• EASYOCR_UNLOAD_TIMEOUT：自動アンロードまでの非アクティブ時間（秒）（デフォルト：300、0で無効）
• UNLOAD_JOBDONE：trueの場合、デフォルトでOCRの呼び出しごとにモデルをアンロードします（デフォルト：false）

対応言語

EasyOCRは、次の言語を含む80以上の言語に対応しています。

• en - 英語
• ch_sim - 簡体字中国語
• ch_tra - 繁体字中国語
• ja - 日本語
• ko - 韓国語
• fr - フランス語
• de - ドイツ語
• es - スペイン語
• その他多数...

GPU/CPUの設定

GPUの使用可否は、easyocr-mcp.pyを起動する環境内で利用可能なPyTorchのインストールによって決まります。Python312から--system-site-packagesを指定してuvの仮想環境を作成すると、そのインタープリターにインストール済みのAMD対応PyTorchをサーバーで再利用できます。

簡単な確認コマンド：

uv run --no-sync python test-gpu.py
uv run --no-sync python test.py
uv run --no-sync python test_mcp_tools.py

このリポジトリで検証済みのAMD環境では、test-gpu.pyにより次の結果が報告されます。

• ROCm対応のtorchビルド
• cuda_available=True
• 空ではないhip_version