EasyOCR MCP 서버

EasyOCR 라이브러리를 사용하여 OCR 기능을 제공하는 MCP(Model Context Protocol) 서버입니다.

EasyOCR 소개: EasyOCR은 JaidedAI에서 개발한 오픈 소스 광학 문자 인식(OCR) 라이브러리입니다. 80개 이상의 언어를 지원하고 GPU 가속을 제공하며, 사용 편의성과 높은 정확도로 잘 알려져 있습니다. EasyOCR은 이미지, 스캔 문서, 사진에서 텍스트를 추출할 수 있어 다양한 OCR 작업에 적합합니다. 자세한 내용은 EasyOCR GitHub 저장소를 방문하세요.

주요 기능

• 3가지 OCR 도구: Base64, 파일, URL을 통한 이미지 처리

• 다국어 지원: 동적 선택이 가능한 80개 이상의 언어 지원

• 유연한 출력: 텍스트 전용 또는 좌표와 신뢰도가 포함된 상세 결과 선택 가능

• 성능 최적화: 더 나은 성능을 위한 리더 캐싱

• 메모리 제어: 자동 언로드 및 요청별 언로드 옵션

• 네이티브 EasyOCR 출력: EasyOCR의 원본 형식 반환

Related MCP server: RapidOCR MCP Server

설치

GPU 설정

프로젝트 환경을 만들기 전에 GPU 경로 중 하나를 선택하세요.

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는 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 지원 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가 lockfile에서 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 venv를 생성하면, 서버는 해당 인터프리터에 설치된 기존 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