Skip to main content
Glama

Umi-OCR MCP Server

简体中文 | English

MCP 프로토콜을 통해 Umi-OCR v2 로컬 OCR 기능을 AI 에이전트(Hermes, Claude Code, Codex 등)에 노출합니다.

Umi-OCR 프로세스를 자동으로 실행하며, 수동으로 서비스를 시작할 필요가 없습니다.

디렉터리 구조

Umi-OCR-MCP/
├── server.py          # MCP 服务器(核心)
├── pyproject.toml     # 依赖声明(uv run 自动安装)
├── requirements.txt   # pip 依赖声明(备选)
├── config.yaml        # Hermes config 接入模板
└── README.md

Related MCP server: Vision MCP

사전 요구 사항

의존성

설명

Umi-OCR v2.1.5+

umi-ocr.com에서 **Paddle 버전(권장)**을 다운로드하여 설치한 후 HTTP API를 활성화합니다(설정 -> 서비스 -> HTTP API 활성화, 기본 포트 1224)

Python 3.11+

uv로 관리하는 것을 권장합니다

uv

패키지 관리자. uv run으로 종속성을 자동 설치하는 데 사용합니다

빠른 시작

1. Umi-OCR 경로 확인

기본 경로: YOUR_UMI_OCR_PATH\Umi-OCR.exe

다른 경로인 경우 환경 변수 UMI_OCR_EXE로 지정합니다.

Windows 참고: 경로에 중국어/공백/특수 문자가 포함된 경우 YAML 및 환경 변수에서 올바르게 이스케이프하세요.

2. MCP 서비스 테스트

cd YOUR_PROJECT_PATH\Umi-OCR-MCP
uv run server.py

uv run을 처음 실행하면 자동으로 pyproject.toml을 읽어 임시 가상 환경을 만들고 mcp, requests 종속성을 설치합니다.

3. Hermes Agent 연동

config.yaml 내용을 Hermes의 config.yaml에 있는 mcp_servers 섹션에 병합합니다:

mcp_servers:
  umi-ocr-mcp:
    command: uv
    args:
      - run
      - --directory
      - YOUR_PROJECT_PATH/Umi-OCR-MCP
      - YOUR_PROJECT_PATH/Umi-OCR-MCP/server.py
    env:
      UMI_OCR_URL: "http://127.0.0.1:1224/api/ocr"
      UMI_OCR_EXE: "YOUR_UMI_OCR_PATH\\Umi-OCR.exe"

핵심: --directory 인자는 uv에게 pyproject.toml을 찾을 위치를 알려줍니다. 생략할 수 없습니다. 생략하면 uv가 종속성을 찾지 못해 바로 ModuleNotFoundError가 발생합니다.

경로 형식: 슬래시 D:/path/to/를 권장합니다. 백슬래시는 YAML에서 D:\\path\\to\\로 이스케이프해야 합니다.

작동 원리

AI Agent -> MCP stdio -> server.py
  1. 检测端口 1224 是否开放
  2. 未开放 -> 自动启动 Umi-OCR.exe(指数退避等待,最长 30s)
  3. 开放 -> 调用 HTTP API 识别图片
  4. OCR 文本 -> 置信度过滤(>0.85)
  5. 轻量后处理(常见 OCR typo 修正)
  6. 返回纯文本给 Agent

서비스 유지

extract_text_umi_v2를 호출할 때마다 포트를 자동으로 감지합니다. Umi-OCR 프로세스가 예기치 않게 종료된 경우 다음 호출 시 자동으로 다시 실행되며 수동 개입이 필요하지 않습니다.

후처리 규칙

내장 정규식 치환으로, 모호함이 없는 OCR 흔한 오류를 수정합니다(AI 이해에 영향을 주지 않는 것은 수정하지 않음):

원본

수정

packspace

backspace

AMDV

AMD-V

Windows102004

Windows 10 2004

打并

打开

重新新

重新

후처리는 확실한 OCR 노이즈만 수정하며, 규칙 범위를 벗어난 것은 원본 그대로 두어 AI가 문맥으로 이해하도록 합니다.

자주 묻는 질문

ModuleNotFoundError: No module named 'requests'

uv run은 기본적으로 격리된 환경을 사용하므로 전역 패키지를 볼 수 없습니다.

해결책: 프로젝트에 이미 pyproject.toml이 포함되어 있습니다. uv run --directory <프로젝트 디렉터리>로 시작하면 uv가 자동으로 종속성을 설치합니다.

Umi-OCR 시작 시간 초과

  • UMI_OCR_EXE 경로가 올바른지 확인하세요

  • Umi-OCR을 처음 시작할 때 PaddleOCR 모델을 로드해야 하므로, 느린 머신에서는 15-30초가 걸릴 수 있습니다

  • Umi-OCR 설정에서 "시작 시 자동 실행" 또는 "트레이로 최소화"를 활성화하면 매번 기다릴 필요가 없습니다

API 오류 코드 반환

Umi-OCR v2 API 형식:

POST /api/ocr
{"base64": "<base64字符串>"}

반환:

{"code": 100, "data": [{"text":"...","score":0.99}], "msg":"success"}
  • code=100: 성공

  • code=300: Base64 디코딩 실패(배열이 아닌 문자열을 전달함)

  • code=802: base64 필드 누락

다른 컴퓨터에 배포

  1. uv 설치

  2. Umi-OCR 설치(umi-ocr.com에서 Paddle 버전 다운로드) 및 HTTP API 활성화(포트 1224)

  3. config.yaml 및 server.py의 기본 경로 수정

  4. 포트 1224가 사용 중이 아닌지 확인

  5. 첫 uv run 시 인터넷 연결로 종속성을 자동 다운로드해야 함

API 참조

도구 개요

도구

용도

카테고리

Token 특징

quick_ocr_status

간결한 서비스 상태

확인

~5자 출력만

check_ocr_status

전체 서비스 상태

확인

~200자 출력

extract_text_umi_v2

단일 이미지 OCR

핵심

표준 출력

ocr_image_base64

Base64 직접 OCR

핵심

파일 쓰기 단계 생략

ocr_batch

여러 이미지 배치 OCR

배치

한 번의 호출로 여러 이미지 처리

ocr_directory

디렉터리 스캔 배치 OCR

배치

list + 목록 생성 생략

ocr_pdf_page

PDF 단일 페이지 직접 OCR

PDF

렌더링 + 파일 저장 단계 생략

quick_ocr_status

간결한 상태 확인. 높은 빈도의 폴링에 적합합니다.

参数:
  无

返回:
  "running" | "stopped" | "error: ..."

Token 비교: ~5자 vs check_ocr_status의 ~200자, 97% 절약.

check_ocr_status

전체 서비스 상태 정보.

参数:
  无

返回:
  服务运行状态、监听地址、API 端点、可执行文件路径

extract_text_umi_v2

로컬 이미지의 텍스트를 OCR로 추출합니다. 문단 병합과 신뢰도 필터링이 내장되어 있습니다.

参数:
  file_path: str              -- 图片绝对路径(必填)
  is_handwritten: bool        -- 是否手写笔记,默认 False

返回:
  str                         -- 识别文本,或错误信息

ocr_image_base64

Base64로 인코딩된 이미지에서 직접 텍스트를 추출하여 파일 쓰기 단계를 생략합니다.

参数:
  image_base64: str           -- Base64 编码字符串(含 data URL 前缀亦可)
  is_handwritten: bool        -- 是否手写笔记,默认 False

返回:
  str                         -- 识别文本,或错误信息

ocr_batch

여러 로컬 이미지를 배치 OCR하여 한 번의 호출로 모든 결과를 반환합니다.

参数:
  file_paths: List[str]       -- 图片绝对路径列表
  is_handwritten: bool        -- 是否手写笔记,默认 False

返回:
  str                         -- 按输入顺序的分隔线分区结果

ocr_directory ⭐ v1.1 신규

디렉터리 아래의 모든 이미지를 스캔하여 배치 OCR합니다. 재귀 모드에서는 하위 디렉터리도 처리할 수 있습니다.

参数:
  directory_path: str         -- 目录绝对路径(必填)
  extensions: str             -- 逗号分隔的扩展名,默认 "png,jpg,jpeg,bmp,webp"
  recursive: bool             -- 是否递归子目录,默认 False
  is_handwritten: bool        -- 是否手写笔记,默认 False
  confidence_threshold: float -- 置信度阈值,默认 0.85

返回:
  str                         -- 紧凑格式:[总数] + 文件名 + 文本

ocr_pdf_page ⭐ v1.1 신규

PDF 지정 페이지를 직접 이미지로 렌더링하여 OCR합니다. 한 번에 완료됩니다. PyMuPDF에 의존합니다.

参数:
  pdf_path: str               -- PDF 文件绝对路径(必填)
  page_number: int            -- 页码(1-based),默认 1
  is_handwritten: bool        -- 是否手写笔记,默认 False
  dpi: int                    -- 渲染分辨率,默认 200
  confidence_threshold: float -- 置信度阈值,默认 0.85

返回:
  str                         -- 识别文本,或错误信息

신뢰도 임계값 설명

모든 OCR 도구는 내부적으로 confidence_threshold를 사용해 저품질 결과를 필터링합니다. 직접 제어가 필요할 때는 새 도구에 노출된 매개변수를 사용하세요:

시나리오

권장 임계값

설명

선명한 인쇄체

0.90+

초고정밀, 없느니만 못함

표준 문서

0.85 (기본값)

정밀도와 재현율 균형

스캔본 교재

0.70-0.80

종이 품질이 일정하지 않아 더 높은 허용도 필요

손글씨 노트

0.60-0.75

손글씨 인식률은 자연히 낮음

MCP 고정 명령어(Prompts)

MCP 프로토콜은 Prompts — 사전 정의된 고정 명령어 템플릿을 지원합니다. 에이전트는 전용 도구 get_prompt(name)으로 이를 호출하며, 표준화된 단계별 워크플로우 지침을 반환받습니다.

server.py에는 가장 흔한 OCR 시나리오를 다루는 3개의 Prompt가 내장되어 있습니다.

Hermes에서 호출

MCP 연결을 재시작하면 Hermes가 자동으로 mcp__umi_ocr__get_prompt 도구를 등록합니다. 호출 방법:

# 列出所有可用 Prompt
mcp__umi_ocr__list_prompts()

# 调取特定 Prompt
mcp__umi_ocr__get_prompt(name="ocr-workflow-quick")

Prompts는 지침 텍스트를 반환합니다(실행 결과가 아님). 에이전트는 이를 읽고 단계에 따라 해당 Tool을 호출하여 실제 OCR을 수행합니다.


ocr-workflow-quick

단일 이미지 빠른 OCR 표준 절차.

단계

작업

도구

1

서비스 온라인 확인

quick_ocr_status

2

텍스트 추출

extract_text_umi_v2(file_path)

3

품질 부족 → 임계값 낮춰 재시도

extract_text_umi_v2(..., confidence_threshold=0.65)

적용: 스크린샷, 단일 시험지 사진, 칠판 촬영.


ocr-workflow-pdf

PDF 페이지별 OCR 표준 절차.

단계

작업

도구

1

서비스 온라인 확인

quick_ocr_status

2

첫 페이지로 품질 시험

ocr_pdf_page(pdf_path, page_number=1)

3

텍스트가 흐림 → DPI를 300으로 높임

ocr_pdf_page(..., dpi=300)

4

누락이 심함 → 임계값을 0.70으로 낮춤

ocr_pdf_page(..., confidence_threshold=0.70)

5

품질 OK → 페이지별 추출

반복 ocr_pdf_page(pdf_path, page_number=N)

적용: 스캔본 수능 기출 PDF, 전자 교재, 논문.


ocr-workflow-batch

전체 교재/시험지 배치 OCR 표준 절차.

단계

작업

도구

1

서비스 온라인 확인

quick_ocr_status

2

디렉터리 아래 모든 이미지 스캔

ocr_directory(dir, recursive=true)

3

2-3개 결과 샘플 확인

수동 또는 Agent 품질 판단

4

일부 실패 → 개별 재시도

extract_text_umi_v2(path, confidence_threshold=0.65)

5

전체 문서로 이어붙이기

파일명 순서대로 정렬하여 병합

적용: 페이지별로 스캔하여 여러 이미지로 저장된 전체 교재, 여러 페이지 시험지 모음.

Available Tools

7 tools
check_ocr_statusA

检查 Umi-OCR 服务是否在运行以及基本状态信息。

节省 token 场景:在发起重要的 OCR 任务前,先确认服务可用, 避免在服务未启动时发起多次失败的 OCR 调用。

返回: 服务运行状态、监听地址、可执行文件路径等信息。

Inputs: no named parameters. Returns: result

extract_text_umi_v2A

调用 Umi-OCR v2.1.5 提取本地图片文本。 已内置段落合并与置信度过滤,极致节约 Token。 专为 AI 阅读理解优化:自动按 Umi-OCR 段落规则分块 + 轻量后处理。

参数: file_path: 图片的绝对本地路径 is_handwritten: 是否手写笔记(切换手写模型),默认 False

Inputs: file_path (required), is_handwritten. Returns: result

ocr_batchA

批量 OCR 多张本地图片,一次调用返回所有结果。

节省 token 场景:需要 OCR 多张图片时,避免多次 MCP 调用的 往返开销,将多张图片合并为一次调用。

参数: file_paths: 图片的绝对本地路径列表 is_handwritten: 是否手写笔记,默认 False

返回: 按输入顺序返回每张图片的 OCR 结果,用分隔线区隔。

Inputs: file_paths (required), is_handwritten. Returns: result

ocr_directoryA

批量 OCR 目录下所有图片。

节省 token 场景:无需先列出目录再构建文件列表,一步完成 目录扫描 + 批量 OCR。适合整本扫描版教辅的批量提取。

参数: directory_path: 目录绝对路径 extensions: 逗号分隔的扩展名(不含点),默认 png,jpg,jpeg,bmp,webp recursive: 是否递归子目录,默认 False is_handwritten: 是否手写笔记,默认 False confidence_threshold: 置信度阈值,默认 0.85

返回: 按文件名排序的识别结果,紧凑格式(总数 + 文件名 + 文本)。

Inputs: directory_path (required), recursive, extensions, is_handwritten, +1 more. Returns: result

ocr_image_base64B

直接从 base64 编码的图片中提取文本。

节省 token 场景:当图片已经以 base64 形式存在(如粘贴板、 其他工具返回的图片数据)时,省去写入文件的步骤, 一步 OCR 到文本。

参数: image_base64: 图片的 base64 编码字符串(含或不含 data URL 前缀均可) is_handwritten: 是否手写笔记,默认 False

Inputs: image_base64 (required), is_handwritten. Returns: result

ocr_pdf_pageA

OCR 提取 PDF 指定页文本。

节省 token 场景:绕过 PDF→截图→存文件→OCR 的多步工作流, 一步到位。对常见的高考真题 PDF、扫描版教辅尤为高效。

参数: pdf_path: PDF 文件绝对路径 page_number: 页码(1-based,默认第 1 页) is_handwritten: 是否手写笔记,默认 False dpi: 渲染分辨率,默认 200(OCR 精度与速度的平衡点) confidence_threshold: 置信度阈值,默认 0.85

返回: 识别文本或错误信息

Inputs: pdf_path (required), dpi, page_number, is_handwritten, +1 more. Returns: result

quick_ocr_statusA

极简状态检查,仅返回 "running" 或 "stopped"。

节省 token 场景:替代 check_ocr_status 的完整输出(~200 tokens), 仅需 ~10 tokens 确认服务状态。适用于高频轮询场景。

返回: "running" 或 "stopped" 或 "error: ..."

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation4/5

    Tools are mostly distinct: OCR methods target different input types (file, base64, PDF, batch, directory). The two status-check tools serve different granularities (detailed vs quick), but their overlap could cause slight confusion despite clear descriptions.

    Naming Consistency2/5

    Naming is inconsistent: some tools use 'ocr_' prefix (ocr_batch, ocr_directory), others use different patterns (check_ocr_status, quick_ocr_status, extract_text_umi_v2). The 'extract_text_umi_v2' name includes a version suffix, breaking convention.

    Tool Count5/5

    With 7 tools, the set is well-scoped for an OCR server. Each tool has a clear role: status checks, single-image OCR from various sources, batch, and directory scanning. No unnecessary tools.

    Completeness4/5

    Covers the main OCR workflow: status check, single image from file/base64/PDF, batch, and directory. Minor gaps like multi-page PDF OCR or clipboard input are absent but not critical for the core use case.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables analysis of local images through Kimi (Moonshot AI) vision models via the MCP protocol, supporting features like OCR and long context understanding.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables any MCP client to perform image understanding and OCR via any OpenAI-compatible vision-language model. Supports local, private inference without images leaving the machine.
      2
      27 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that exposes Xiaomi's MiMo-V2.5 vision model as an inspect_image tool, enabling AI agents to analyze images with structured JSON output including OCR, visual evidence, and normalized coordinates.
      24 npm
      MIT