EasyOCR MCP tool

EasyOCR MCP 服务

一个通过 EasyOCR 库提供 OCR 功能的模型上下文协议（MCP）服务。

关于 EasyOCR：
EasyOCR 是 JaidedAI 开发的开源光学字符识别（OCR）库。它支持 80 多种语言，提供 GPU 加速，以易于使用和准确率高而闻名。EasyOCR 可以从图像、扫描文档和照片中提取文本，适用于各种 OCR 任务。更多详情请访问 EasyOCR GitHub 仓库。

功能

• 3 种 OCR 工具：处理 base64、文件或 URL 中的图像
• 多语言支持：支持 80 多种语言，可动态选择
• 灵活的输出：可选择仅输出文本，或输出包含坐标和置信度的详细结果
• 性能优化：缓存 Reader 以提升性能
• 内存控制：支持自动卸载和按请求卸载
• 原生 EasyOCR 输出：返回 EasyOCR 的原始格式

安装

GPU 设置

创建项目环境前，请选择一种 GPU 方案。

NVIDIA GPU

使用 PyTorch 官方安装选择器，根据操作系统、Python 版本和 CUDA 版本选择安装方式：

• 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 指出，Windows 上尚不支持完整的 ROCm 技术栈

官方参考资料：

• 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-enabled 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

这样可以继续使用 uv 管理项目，同时指定现有的 Python312 安装。如果不使用 --system-site-packages，常规 venv 将无法访问基础解释器中已安装的软件包。初始设置完成后，请使用 uv run --no-sync，以免 uv 从锁文件重新安装仅支持 CPU 的 PyTorch wheel。

使用方法

可用工具

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