Umi-OCR MCP Server
Umi-OCR MCP Server
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.mdRelated 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 |
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.pyLa 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
--directoryle indica a uv dónde encontrarpyproject.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 comoD:\\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. 返回纯文本给 AgentMantenimiento 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_EXEsea correctaLa 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
Instala uv
Instala Umi-OCR (descarga la versión Paddle desde umi-ocr.com) y activa la API HTTP (puerto 1224)
Modifica las rutas predeterminadas en
config.yamlyserver.pyConfirma que el puerto 1224 no esté ocupado
La primera ejecución de
uv runrequiere 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 |
| Estado del servicio mínimo | Comprobación | Solo salida de ~5 caracteres |
| Estado completo del servicio | Comprobación | Salida de ~200 caracteres |
| OCR de una sola imagen | Núcleo | Salida estándar |
| OCR directo desde Base64 | Núcleo | Evita el paso de escribir archivos |
| OCR por lotes de varias imágenes | Lote | Procesa varias imágenes en una sola llamada |
| OCR por lotes escaneando un directorio | Lote | Evita listar + construir la lista |
| OCR directo de una página de 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 |
|
2 | Extraer texto |
|
3 | Calidad insuficiente → reintentar con umbral más bajo |
|
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 |
|
2 | OCR de la primera página para probar la calidad |
|
3 | Texto borroso → aumentar DPI a 300 |
|
4 | Faltan muchos caracteres → bajar el umbral a 0.70 |
|
5 | Calidad OK → extraer página por página | Bucle |
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 |
|
2 | Escanear todas las imágenes del directorio |
|
3 | Inspeccionar 2-3 resultados | Evaluación de calidad manual o por el agente |
4 | Fallos puntuales → reintentar individualmente |
|
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 toolscheck_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
Scored across 7 tools
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 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.
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.
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
Related MCP Connectors
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables analysis of local images through Kimi (Moonshot AI) vision models via the MCP protocol, supporting features like OCR and long context understanding.MIT
- AlicenseAqualityCmaintenanceEnables 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.227 npmMIT
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP stdio server that enables LLM agents to invoke the MiMo Vision model for local image understanding and OCR via the OpenCode API.MIT
- AlicenseNot gradedqualityDmaintenanceA 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 npmMIT