Umi-OCR MCP Server
This server exposes Umi-OCR's local OCR capabilities to AI agents over MCP, enabling text extraction from images, directories, and PDFs with automatic service management and workflow prompts.
Check OCR service status:
quick_ocr_statusfor a minimal online/offline check,check_ocr_statusfor detailed status info.Extract text from a single local image with
extract_text_umi_v2.OCR directly from a Base64-encoded image with
ocr_image_base64, avoiding temporary files.Batch OCR multiple local images in one call with
ocr_batch.Scan and OCR all images in a directory, optionally recursively, with
ocr_directory.OCR a specific PDF page directly via
ocr_pdf_page, with configurable DPI and confidence threshold.Control OCR quality through confidence thresholds, including lower thresholds for handwriting.
Use built-in MCP prompt templates for quick single-image OCR, PDF workflows, and batch document processing.
Automatically detect, start, and keep alive the Umi-OCR process, with built-in OCR text post-processing corrections.
Integrates Umi-OCR local OCR capabilities into Hermes AI agent, enabling image text extraction, batch OCR, PDF OCR, and directory scanning through MCP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Umi-OCR MCP Server extract text from D:\photos\document.png"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Umi-OCR MCP Server
Expose the local OCR capabilities of Umi-OCR v2 to AI Agents (Hermes, Claude Code, Codex, etc.) via the MCP protocol.
Automatically launches the Umi-OCR process — no need to start the service manually.
Directory Structure
Umi-OCR-MCP/
├── server.py # MCP 服务器(核心)
├── pyproject.toml # 依赖声明(uv run 自动安装)
├── requirements.txt # pip 依赖声明(备选)
├── config.yaml # Hermes config 接入模板
└── README.mdRelated MCP server: Vision MCP
Prerequisites
Dependency | Description |
Umi-OCR v2.1.5+ | Download the Paddle version (recommended) from umi-ocr.com, install it, then enable the HTTP API (Settings -> Service -> Enable HTTP API, default port 1224) |
Python 3.11+ | Recommended to manage via uv |
uv | Package manager, used by |
Quick Start
1. Confirm the Umi-OCR Path
Default path: YOUR_UMI_OCR_PATH\Umi-OCR.exe
If different, specify it via the environment variable UMI_OCR_EXE.
Windows note: if the path contains Chinese characters, spaces, or special characters, make sure to escape them correctly in YAML and environment variables.
2. Test the MCP Service
cd YOUR_PROJECT_PATH\Umi-OCR-MCP
uv run server.pyThe first uv run automatically reads pyproject.toml, creates a temporary virtual environment, and installs the mcp and requests dependencies.
3. Connect to Hermes Agent
Merge the contents of config.yaml into the mcp_servers section of Hermes' config.yaml:
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"Key point: the
--directoryargument tells uv where to findpyproject.toml— it cannot be omitted. Without it, uv cannot find the dependencies and will directly raise ModuleNotFoundError.
Path format: forward slashes are recommended, e.g.
D:/path/to/. Backslashes must be escaped in YAML asD:\\path\\to\\.
How It Works
AI Agent -> MCP stdio -> server.py
1. 检测端口 1224 是否开放
2. 未开放 -> 自动启动 Umi-OCR.exe(指数退避等待,最长 30s)
3. 开放 -> 调用 HTTP API 识别图片
4. OCR 文本 -> 置信度过滤(>0.85)
5. 轻量后处理(常见 OCR typo 修正)
6. 返回纯文本给 AgentService Keep-Alive
Each call to extract_text_umi_v2 automatically checks the port. If the Umi-OCR process exits unexpectedly, the next call will automatically relaunch it — no manual intervention needed.
Post-Processing Rules
Built-in regex replacements that fix unambiguous, common OCR errors (things that don't affect AI understanding are left untouched):
Original | Corrected |
packspace | backspace |
AMDV | AMD-V |
Windows102004 | Windows 10 2004 |
打并 | 打开 |
重新新 | 重新 |
Post-processing only fixes OCR noise that is certain. Anything outside the rule scope is left as-is for the AI to interpret.
FAQ
ModuleNotFoundError: No module named 'requests'
uv run uses an isolated environment by default and cannot see globally installed packages.
Solution: the project already includes pyproject.toml. Make sure to launch with uv run --directory <project directory> — uv will install the dependencies automatically.
Umi-OCR Startup Timeout
Check that the
UMI_OCR_EXEpath is correctThe first launch of Umi-OCR needs to load the PaddleOCR model; slower machines may need 15-30 seconds
You can enable "Start on boot" or "Minimize to tray" in Umi-OCR settings to avoid waiting each time
API Returns an Error Code
Umi-OCR v2 API format:
POST /api/ocr
{"base64": "<base64字符串>"}Returns:
{"code": 100, "data": [{"text":"...","score":0.99}], "msg":"success"}code=100: success
code=300: Base64 decoding failed (an array was passed instead of a string)
code=802: missing base64 field
Deploying on Other Machines
Install uv
Install Umi-OCR (download the Paddle version from umi-ocr.com) and enable the HTTP API (port 1224)
Modify the default paths in
config.yamlandserver.pyConfirm port 1224 is not occupied
The first
uv runneeds network access to auto-download dependencies
API Reference
Tool Overview
Tool | Purpose | Category | Token Characteristics |
| Minimal service status | Check | Only ~5 chars output |
| Full service status | Check | ~200 chars output |
| OCR for a single image | Core | Standard output |
| OCR directly from Base64 | Core | Skips the file-writing step |
| Batch OCR for multiple images | Batch | One call handles multiple images |
| Directory-scan batch OCR | Batch | Skips list + manifest building |
| OCR a single PDF page directly | Skips rendering + saving steps |
quick_ocr_status
Minimal status check, suitable for high-frequency polling.
参数:
无
返回:
"running" | "stopped" | "error: ..."Token comparison: ~5 chars vs ~200 chars for check_ocr_status — saves 97%.
check_ocr_status
Full service status information.
参数:
无
返回:
服务运行状态、监听地址、API 端点、可执行文件路径extract_text_umi_v2
OCR to extract text from a local image. Includes built-in paragraph merging and confidence filtering.
参数:
file_path: str -- 图片绝对路径(必填)
is_handwritten: bool -- 是否手写笔记,默认 False
返回:
str -- 识别文本,或错误信息ocr_image_base64
Extract text directly from a Base64-encoded image, skipping the file-writing step.
参数:
image_base64: str -- Base64 编码字符串(含 data URL 前缀亦可)
is_handwritten: bool -- 是否手写笔记,默认 False
返回:
str -- 识别文本,或错误信息ocr_batch
Batch OCR for multiple local images; one call returns all results.
参数:
file_paths: List[str] -- 图片绝对路径列表
is_handwritten: bool -- 是否手写笔记,默认 False
返回:
str -- 按输入顺序的分隔线分区结果ocr_directory ⭐ New in v1.1
Scans all images in a directory and performs batch OCR. In recursive mode, subdirectories are handled too.
参数:
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 ⭐ New in v1.1
Directly renders a specified PDF page as an image and OCRs it in one step. Depends on PyMuPDF.
参数:
pdf_path: str -- PDF 文件绝对路径(必填)
page_number: int -- 页码(1-based),默认 1
is_handwritten: bool -- 是否手写笔记,默认 False
dpi: int -- 渲染分辨率,默认 200
confidence_threshold: float -- 置信度阈值,默认 0.85
返回:
str -- 识别文本,或错误信息Confidence Threshold Notes
All OCR tools internally use confidence_threshold to filter out low-quality results.
When you need direct control, use the parameter exposed by the new tools:
Scenario | Recommended Threshold | Description |
Clear printed text | 0.90+ | Extremely high precision, better to miss than to err |
Standard documents | 0.85 (default) | Balance between precision and recall |
Scanned workbooks | 0.70-0.80 | Paper quality varies, needs more tolerance |
Handwritten notes | 0.60-0.75 | Handwriting recognition rates are naturally lower |
MCP Fixed Instructions (Prompts)
The MCP protocol supports Prompts — predefined fixed instruction templates.
The Agent retrieves them via the dedicated tool get_prompt(name), which returns standardized step-by-step workflow instructions.
server.py ships with 3 built-in Prompts covering the most common OCR scenarios.
Calling Them in Hermes
After restarting the MCP connection, Hermes automatically registers the mcp__umi_ocr__get_prompt tool.
Call it like this:
# 列出所有可用 Prompt
mcp__umi_ocr__list_prompts()
# 调取特定 Prompt
mcp__umi_ocr__get_prompt(name="ocr-workflow-quick")Prompts return instruction text (not execution results). The Agent reads them and then calls the corresponding Tools step by step to perform the actual OCR.
ocr-workflow-quick
Standard workflow for quick OCR of a single image.
Step | Action | Tool |
1 | Confirm the service is online |
|
2 | Extract text |
|
3 | Poor quality → retry with lower threshold |
|
Applies to: screenshots, a single exam-paper photo, photos of a whiteboard.
ocr-workflow-pdf
Standard workflow for page-by-page PDF OCR.
Step | Action | Tool |
1 | Confirm the service is online |
|
2 | OCR page 1 to probe quality |
|
3 | Blurry text → raise DPI to 300 |
|
4 | Many missing characters → lower threshold to 0.70 |
|
5 | Quality OK → extract page by page | Loop |
Applies to: scanned college-entrance-exam PDFs, digital workbooks, papers.
ocr-workflow-batch
Standard workflow for batch OCR of a full workbook / exam-paper set.
Step | Action | Tool |
1 | Confirm the service is online |
|
2 | Scan all images in the directory |
|
3 | Spot-check 2-3 results | Human or Agent judges the quality |
4 | Individual failures → retry individually |
|
5 | Assemble into a full document | Merge by sorting file names |
Applies to: a full textbook scanned page-by-page into multiple images, multi-page exam-paper collections.
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.
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.760 npmMIT
- 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