Umi-OCR MCP Server
Umi-OCR MCP Server
Stellt die lokale OCR-Fähigkeit von Umi-OCR v2 über das MCP-Protokoll für KI-Agenten (Hermes, Claude Code, Codex usw.) bereit.
Startet den Umi-OCR-Prozess automatisch, ohne den Dienst manuell starten zu müssen.
Verzeichnisstruktur
Umi-OCR-MCP/
├── server.py # MCP 服务器(核心)
├── pyproject.toml # 依赖声明(uv run 自动安装)
├── requirements.txt # pip 依赖声明(备选)
├── config.yaml # Hermes config 接入模板
└── README.mdRelated MCP server: Vision MCP
Voraussetzungen
Abhängigkeit | Beschreibung |
Umi-OCR v2.1.5+ | Laden Sie die Paddle-Version (empfohlen) von umi-ocr.com herunter, installieren Sie sie und aktivieren Sie die HTTP-API (Einstellungen -> Dienste -> HTTP-API aktivieren, Standardport 1224) |
Python 3.11+ | Empfohlen über uv verwalten |
uv | Paketmanager, verwendet für |
Schnellstart
1. Umi-OCR-Pfad bestätigen
Standardpfad: YOUR_UMI_OCR_PATH\Umi-OCR.exe
Falls abweichend, über die Umgebungsvariable UMI_OCR_EXE angeben.
Windows-Hinweis: Wenn der Pfad chinesische Zeichen/Leerzeichen/Sonderzeichen enthält, stellen Sie sicher, dass er in YAML und Umgebungsvariablen korrekt maskiert ist.
2. MCP-Dienst testen
cd YOUR_PROJECT_PATH\Umi-OCR-MCP
uv run server.pyBeim ersten uv run wird automatisch pyproject.toml gelesen, eine temporäre virtuelle Umgebung erstellt und die Abhängigkeiten mcp und requests installiert.
3. Hermes-Agent anbinden
Fügen Sie den Inhalt von config.yaml in den Abschnitt mcp_servers der config.yaml von Hermes ein:
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"Wichtig: Der Parameter
--directoryteilt uv mit, wopyproject.tomlzu finden ist, und darf nicht weggelassen werden. Ohne ihn findet uv die Abhängigkeiten nicht und meldet direkt ModuleNotFoundError.
Pfadformat: Empfohlen werden Schrägstriche
D:/path/to/. Backslashes müssen in YAML alsD:\\path\\to\\maskiert werden.
Funktionsweise
AI Agent -> MCP stdio -> server.py
1. 检测端口 1224 是否开放
2. 未开放 -> 自动启动 Umi-OCR.exe(指数退避等待,最长 30s)
3. 开放 -> 调用 HTTP API 识别图片
4. OCR 文本 -> 置信度过滤(>0.85)
5. 轻量后处理(常见 OCR typo 修正)
6. 返回纯文本给 AgentDienst am Leben halten
Bei jedem Aufruf von extract_text_umi_v2 wird der Port automatisch geprüft. Wenn der Umi-OCR-Prozess unerwartet beendet wurde, wird er beim nächsten Aufruf automatisch neu gestartet, ohne manuelles Eingreifen.
Nachbearbeitungsregeln
Integrierte Regex-Ersetzungen zur Korrektur eindeutiger häufiger OCR-Fehler (solche, die das KI-Verständnis nicht beeinträchtigen, werden nicht korrigiert):
Original | Korrektur |
packspace | backspace |
AMDV | AMD-V |
Windows102004 | Windows 10 2004 |
打并 | 打开 |
重新新 | 重新 |
Die Nachbearbeitung korrigiert nur eindeutig bestimmbare OCR-Rauschen. Alles außerhalb der Regeln bleibt unverändert und wird dem KI-Verständnis überlassen.
Häufige Fragen
ModuleNotFoundError: No module named 'requests'
uv run verwendet standardmäßig eine isolierte Umgebung und sieht globale Pakete nicht.
Lösung: Das Projekt enthält bereits pyproject.toml. Stellen Sie sicher, dass Sie mit uv run --directory <Projektverzeichnis> starten; uv installiert die Abhängigkeiten automatisch.
Umi-OCR-Startzeitüberschreitung
Prüfen Sie, ob der Pfad
UMI_OCR_EXEkorrekt istBeim ersten Start muss Umi-OCR das PaddleOCR-Modell laden; auf langsameren Maschinen kann dies 15-30 Sekunden dauern
Sie können in den Umi-OCR-Einstellungen „Autostart" oder „In Taskleiste minimieren" aktivieren, um das Warten zu vermeiden
API gibt Fehlercodes zurück
Umi-OCR v2-API-Format:
POST /api/ocr
{"base64": "<base64字符串>"}Rückgabe:
{"code": 100, "data": [{"text":"...","score":0.99}], "msg":"success"}code=100: Erfolg
code=300: Base64-Dekodierung fehlgeschlagen (Array statt String übergeben)
code=802: base64-Feld fehlt
Bereitstellung auf anderen Computern
uv installieren
Umi-OCR installieren (Paddle-Version von umi-ocr.com herunterladen) und HTTP-API aktivieren (Port 1224)
Standardpfade in
config.yamlundserver.pyändernSicherstellen, dass Port 1224 nicht belegt ist
Beim ersten
uv runwerden die Abhängigkeiten automatisch online heruntergeladen
API-Referenz
Tool-Übersicht
Tool | Zweck | Kategorie | Token-Eigenschaften |
| Minimaler Dienststatus | Prüfung | nur ~5 Zeichen Ausgabe |
| Vollständiger Dienststatus | Prüfung | ~200 Zeichen Ausgabe |
| OCR für einzelnes Bild | Kern | Standardausgabe |
| Direktes OCR aus Base64 | Kern | spart Dateischreibschritt |
| Batch-OCR mehrerer Bilder | Batch | verarbeitet mehrere Bilder in einem Aufruf |
| Verzeichnisscan-Batch-OCR | Batch | spart list + Manifest-Erstellung |
| Direktes OCR einer PDF-Seite | spart Rendering + Dateispeicherschritt |
quick_ocr_status
Minimale Statusprüfung, geeignet für häufiges Polling.
参数:
无
返回:
"running" | "stopped" | "error: ..."Token-Vergleich: ~5 Zeichen vs. ~200 Zeichen bei check_ocr_status, spart 97 %.
check_ocr_status
Vollständige Dienststatusinformationen.
参数:
无
返回:
服务运行状态、监听地址、API 端点、可执行文件路径extract_text_umi_v2
OCR-Extraktion von Text aus lokalen Bildern. Integrierte Absatzzusammenführung und Konfidenzfilterung.
参数:
file_path: str -- 图片绝对路径(必填)
is_handwritten: bool -- 是否手写笔记,默认 False
返回:
str -- 识别文本,或错误信息ocr_image_base64
Extrahiert Text direkt aus Base64-kodierten Bildern, spart den Dateischreibschritt.
参数:
image_base64: str -- Base64 编码字符串(含 data URL 前缀亦可)
is_handwritten: bool -- 是否手写笔记,默认 False
返回:
str -- 识别文本,或错误信息ocr_batch
Batch-OCR mehrerer lokaler Bilder, ein Aufruf liefert alle Ergebnisse.
参数:
file_paths: List[str] -- 图片绝对路径列表
is_handwritten: bool -- 是否手写笔记,默认 False
返回:
str -- 按输入顺序的分隔线分区结果ocr_directory ⭐ Neu in v1.1
Scannt alle Bilder im Verzeichnis und führt Batch-OCR durch. Im rekursiven Modus werden Unterverzeichnisse verarbeitet.
参数:
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 ⭐ Neu in v1.1
Rendert die angegebene PDF-Seite direkt als Bild und führt OCR durch, alles in einem Schritt. Erfordert PyMuPDF.
参数:
pdf_path: str -- PDF 文件绝对路径(必填)
page_number: int -- 页码(1-based),默认 1
is_handwritten: bool -- 是否手写笔记,默认 False
dpi: int -- 渲染分辨率,默认 200
confidence_threshold: float -- 置信度阈值,默认 0.85
返回:
str -- 识别文本,或错误信息Erläuterung der Konfidenzschwellen
Alle OCR-Tools verwenden intern confidence_threshold zur Filterung minderwertiger Ergebnisse.
Für direkte Steuerung verwenden Sie die Parameter der neuen Tools:
Szenario | Empfohlener Schwellenwert | Beschreibung |
Klarer Drucktext | 0.90+ | Höchste Präzision, lieber nichts als falsch |
Standarddokument | 0.85 (Standard) | Ausgewogenheit zwischen Präzision und Recall |
Gescannte Lernhilfen | 0.70-0.80 | Papierqualität variiert, höhere Toleranz nötig |
Handschriftliche Notizen | 0.60-0.75 | Handschrifterkennung ist naturgemäß niedriger |
MCP-Festbefehle (Prompts)
Das MCP-Protokoll unterstützt Prompts – vordefinierte Festbefehl-Vorlagen.
Der Agent ruft sie über das spezielle Tool get_prompt(name) ab und erhält standardisierte schrittweise Arbeitsablauf-Anweisungen.
server.py enthält bereits 3 Prompts, die die häufigsten OCR-Szenarien abdecken.
In Hermes aufrufen
Nach dem Neustart der MCP-Verbindung registriert Hermes automatisch das Tool mcp__umi_ocr__get_prompt.
Aufrufmethode:
# 列出所有可用 Prompt
mcp__umi_ocr__list_prompts()
# 调取特定 Prompt
mcp__umi_ocr__get_prompt(name="ocr-workflow-quick")Prompts geben Anweisungstext zurück (kein Ausführungsergebnis). Der Agent liest ihn und ruft die entsprechenden Tools schrittweise auf, um die eigentliche OCR durchzuführen.
ocr-workflow-quick
Standardablauf für schnelles OCR eines einzelnen Bildes.
Schritt | Aktion | Tool |
1 | Dienst online bestätigen |
|
2 | Text extrahieren |
|
3 | Unzureichende Qualität → Schwellenwert senken und erneut versuchen |
|
Geeignet für: Screenshots, einzelne Prüfungsfotos, Tafelaufnahmen.
ocr-workflow-pdf
Standardablauf für seitenweises PDF-OCR.
Schritt | Aktion | Tool |
1 | Dienst online bestätigen |
|
2 | OCR der ersten Seite zur Qualitätsprüfung |
|
3 | Text unscharf → DPI auf 300 erhöhen |
|
4 | Viele fehlende Zeichen → Schwellenwert auf 0.70 senken |
|
5 | Qualität OK → seitenweise extrahieren | Schleife |
Geeignet für: Gescannte Abiturprüfungs-PDFs, elektronische Lernhilfen, wissenschaftliche Arbeiten.
ocr-workflow-batch
Standardablauf für Batch-OCR ganzer Lernhilfen/Prüfungen.
Schritt | Aktion | Tool |
1 | Dienst online bestätigen |
|
2 | Alle Bilder im Verzeichnis scannen |
|
3 | 2-3 Ergebnisse stichprobenartig prüfen | Manuell oder durch Agent Qualität beurteilen |
4 | Einzelne Fehlschläge → einzeln erneut versuchen |
|
5 | Zu vollständigem Dokument zusammenfügen | Nach Dateinamen sortiert zusammenführen |
Geeignet für: Ganze Lehrbücher, die seitenweise gescannt und als mehrere Bilder gespeichert wurden, mehrseitige Prüfungssammlungen.
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.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