Skip to main content
Glama

Umi-OCR MCP Server

简体中文 | English

Expone las capacidades de OCR local de Umi-OCR v2 a agentes de IA (Hermes, Claude Code, Codex, etc.) mediante el protocolo MCP.

Inicia automáticamente el proceso de Umi-OCR, sin necesidad de arrancar el servicio manualmente.

Estructura de directorios

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

Related MCP server: Vision MCP

Requisitos previos

Dependencia

Descripción

Umi-OCR v2.1.5+

Descarga la versión Paddle (recomendada) desde umi-ocr.com, instálala y activa la API HTTP (Configuración -> Servicio -> Activar API HTTP, puerto predeterminado 1224)

Python 3.11+

Se recomienda gestionarlo con uv

uv

Gestor de paquetes, se usa para que uv run instale las dependencias automáticamente

Inicio rápido

1. Confirma la ruta de Umi-OCR

Ruta predeterminada: YOUR_UMI_OCR_PATH\Umi-OCR.exe

Si es diferente, especifícala mediante la variable de entorno UMI_OCR_EXE.

Nota para Windows: si la ruta contiene caracteres chinos, espacios o caracteres especiales, asegúrate de escapar correctamente en el YAML y en las variables de entorno.

2. Prueba el servicio MCP

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

La primera ejecución de uv run leerá automáticamente pyproject.toml, creará un entorno virtual temporal e instalará las dependencias mcp y requests.

3. Conecta con Hermes Agent

Fusiona el contenido de config.yaml en la sección mcp_servers del config.yaml de Hermes:

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"

Clave: el parámetro --directory le indica a uv dónde encontrar pyproject.toml; no se puede omitir. Sin él, uv no encuentra las dependencias y lanza directamente ModuleNotFoundError.

Formato de ruta: se recomienda usar barras normales D:/path/to/. Las barras invertidas deben escaparse en YAML como D:\\path\\to\\.

Principio de funcionamiento

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

Mantenimiento del servicio

Cada llamada a extract_text_umi_v2 detecta automáticamente el puerto. Si el proceso de Umi-OCR se cierra inesperadamente, la siguiente llamada lo reinicia automáticamente, sin intervención manual.

Reglas de postprocesamiento

Reemplazos integrados mediante expresiones regulares que corrigen errores comunes de OCR sin ambigüedad (no se corrigen los que no afectan a la comprensión de la IA):

Original

Corregido

packspace

backspace

AMDV

AMD-V

Windows102004

Windows 10 2004

打并

打开

重新新

重新

El postprocesamiento solo corrige el ruido de OCR determinable; lo que queda fuera de las reglas se conserva tal cual para que la IA lo lea y comprenda.

Preguntas frecuentes

ModuleNotFoundError: No module named 'requests'

uv run usa un entorno aislado por defecto y no ve los paquetes globales.

Solución: el proyecto ya incluye pyproject.toml; asegúrate de iniciarlo con uv run --directory <directorio_del_proyecto>, y uv instalará las dependencias automáticamente.

Tiempo de espera agotado al iniciar Umi-OCR

  • Comprueba que la ruta de UMI_OCR_EXE sea correcta

  • La primera vez que se inicia Umi-OCR debe cargar el modelo PaddleOCR; en máquinas lentas puede tardar entre 15 y 30 segundos

  • Puedes activar "Inicio automático" o "Minimizar a la bandeja" en la configuración de Umi-OCR para evitar esperar cada vez

La API devuelve códigos de error

Formato de la API de Umi-OCR v2:

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

Respuesta:

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

  • code=300: error de decodificación Base64 (se pasó un array en lugar de una cadena)

  • code=802: falta el campo base64

Despliegue en otros equipos

  1. Instala uv

  2. Instala Umi-OCR (descarga la versión Paddle desde umi-ocr.com) y activa la API HTTP (puerto 1224)

  3. Modifica las rutas predeterminadas en config.yaml y server.py

  4. Confirma que el puerto 1224 no esté ocupado

  5. La primera ejecución de uv run requiere conexión a internet para descargar las dependencias automáticamente

Referencia de la API

Resumen de herramientas

Herramienta

Uso

Categoría

Características de tokens

quick_ocr_status

Estado del servicio mínimo

Comprobación

Solo salida de ~5 caracteres

check_ocr_status

Estado completo del servicio

Comprobación

Salida de ~200 caracteres

extract_text_umi_v2

OCR de una sola imagen

Núcleo

Salida estándar

ocr_image_base64

OCR directo desde Base64

Núcleo

Evita el paso de escribir archivos

ocr_batch

OCR por lotes de varias imágenes

Lote

Procesa varias imágenes en una sola llamada

ocr_directory

OCR por lotes escaneando un directorio

Lote

Evita listar + construir la lista

ocr_pdf_page

OCR directo de una página de PDF

PDF

Evita los pasos de renderizar + guardar archivo

quick_ocr_status

Comprobación de estado mínima, adecuada para sondeos de alta frecuencia.

参数:
  无

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

Comparación de tokens: ~5 caracteres frente a los ~200 de check_ocr_status, un ahorro del 97%.

check_ocr_status

Información completa del estado del servicio.

参数:
  无

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

extract_text_umi_v2

Extrae texto de imágenes locales mediante OCR. Incluye fusión de párrafos y filtrado por confianza.

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

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

ocr_image_base64

Extrae texto directamente de imágenes codificadas en Base64, omitiendo el paso de escribir archivos.

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

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

ocr_batch

OCR por lotes de varias imágenes locales; una sola llamada devuelve todos los resultados.

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

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

ocr_directory ⭐ Nuevo en v1.1

Escanea todas las imágenes de un directorio y realiza OCR por lotes. En modo recursivo puede procesar subdirectorios.

参数:
  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 ⭐ Nuevo en v1.1

Renderiza directamente la página especificada de un PDF como imagen y realiza el OCR, todo en un solo paso. Depende de PyMuPDF.

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

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

Explicación del umbral de confianza

Todas las herramientas de OCR usan internamente confidence_threshold para filtrar resultados de baja calidad. Cuando se necesita control directo, se usan los parámetros expuestos por las nuevas herramientas:

Escenario

Umbral recomendado

Descripción

Texto impreso nítido

0.90+

Precisión extrema, mejor que falte a que sobre

Documento estándar

0.85 (predeterminado)

Equilibrio entre precisión y recuperación

Material didáctico escaneado

0.70-0.80

Calidad de papel variable, requiere mayor tolerancia

Notas manuscritas

0.60-0.75

La tasa de reconocimiento de escritura a mano es naturalmente baja

Instrucciones fijas de MCP (Prompts)

El protocolo MCP admite Prompts — plantillas de instrucciones fijas predefinidas. El agente las recupera mediante la herramienta dedicada get_prompt(name), que devuelve instrucciones de flujo de trabajo estandarizadas paso a paso.

server.py ya incluye 3 Prompts integrados que cubren los escenarios de OCR más comunes.

Cómo invocarlos en Hermes

Tras reiniciar la conexión MCP, Hermes registrará automáticamente la herramienta mcp__umi_ocr__get_prompt. Forma de invocación:

# 列出所有可用 Prompt
mcp__umi_ocr__list_prompts()

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

Los Prompts devuelven texto de instrucciones (no resultados de ejecución); el agente lo lee y luego llama a la Tool correspondiente siguiendo los pasos para realizar el OCR real.


ocr-workflow-quick

Flujo estándar de OCR rápido para una sola imagen.

Paso

Operación

Herramienta

1

Confirmar que el servicio está en línea

quick_ocr_status

2

Extraer texto

extract_text_umi_v2(file_path)

3

Calidad insuficiente → reintentar con umbral más bajo

extract_text_umi_v2(..., confidence_threshold=0.65)

Aplicable a: capturas de pantalla, fotos de exámenes individuales, fotos de pizarra.


ocr-workflow-pdf

Flujo estándar de OCR página a página para PDF.

Paso

Operación

Herramienta

1

Confirmar que el servicio está en línea

quick_ocr_status

2

OCR de la primera página para probar la calidad

ocr_pdf_page(pdf_path, page_number=1)

3

Texto borroso → aumentar DPI a 300

ocr_pdf_page(..., dpi=300)

4

Faltan muchos caracteres → bajar el umbral a 0.70

ocr_pdf_page(..., confidence_threshold=0.70)

5

Calidad OK → extraer página por página

Bucle ocr_pdf_page(pdf_path, page_number=N)

Aplicable a: PDF de exámenes de acceso a la universidad escaneados, material didáctico electrónico, artículos académicos.


ocr-workflow-batch

Flujo estándar de OCR por lotes para un libro didáctico completo / conjunto de exámenes.

Paso

Operación

Herramienta

1

Confirmar que el servicio está en línea

quick_ocr_status

2

Escanear todas las imágenes del directorio

ocr_directory(dir, recursive=true)

3

Inspeccionar 2-3 resultados

Evaluación de calidad manual o por el agente

4

Fallos puntuales → reintentar individualmente

extract_text_umi_v2(path, confidence_threshold=0.65)

5

Unir en un documento completo

Fusionar ordenando por nombre de archivo

Aplicable a: libros de texto completos escaneados página a página y guardados como varias imágenes, colecciones de exámenes de varias páginas.

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.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    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