Skip to main content
Glama

Umi-OCR MCP Server

简体中文 | English

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.md

Related 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 uv run zur automatischen Installation von Abhängigkeiten

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.py

Beim 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 --directory teilt uv mit, wo pyproject.toml zu 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 als D:\\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. 返回纯文本给 Agent

Dienst 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_EXE korrekt ist

  • Beim 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

  1. uv installieren

  2. Umi-OCR installieren (Paddle-Version von umi-ocr.com herunterladen) und HTTP-API aktivieren (Port 1224)

  3. Standardpfade in config.yaml und server.py ändern

  4. Sicherstellen, dass Port 1224 nicht belegt ist

  5. Beim ersten uv run werden die Abhängigkeiten automatisch online heruntergeladen

API-Referenz

Tool-Übersicht

Tool

Zweck

Kategorie

Token-Eigenschaften

quick_ocr_status

Minimaler Dienststatus

Prüfung

nur ~5 Zeichen Ausgabe

check_ocr_status

Vollständiger Dienststatus

Prüfung

~200 Zeichen Ausgabe

extract_text_umi_v2

OCR für einzelnes Bild

Kern

Standardausgabe

ocr_image_base64

Direktes OCR aus Base64

Kern

spart Dateischreibschritt

ocr_batch

Batch-OCR mehrerer Bilder

Batch

verarbeitet mehrere Bilder in einem Aufruf

ocr_directory

Verzeichnisscan-Batch-OCR

Batch

spart list + Manifest-Erstellung

ocr_pdf_page

Direktes OCR einer PDF-Seite

PDF

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

quick_ocr_status

2

Text extrahieren

extract_text_umi_v2(file_path)

3

Unzureichende Qualität → Schwellenwert senken und erneut versuchen

extract_text_umi_v2(..., confidence_threshold=0.65)

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

quick_ocr_status

2

OCR der ersten Seite zur Qualitätsprüfung

ocr_pdf_page(pdf_path, page_number=1)

3

Text unscharf → DPI auf 300 erhöhen

ocr_pdf_page(..., dpi=300)

4

Viele fehlende Zeichen → Schwellenwert auf 0.70 senken

ocr_pdf_page(..., confidence_threshold=0.70)

5

Qualität OK → seitenweise extrahieren

Schleife ocr_pdf_page(pdf_path, page_number=N)

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

quick_ocr_status

2

Alle Bilder im Verzeichnis scannen

ocr_directory(dir, recursive=true)

3

2-3 Ergebnisse stichprobenartig prüfen

Manuell oder durch Agent Qualität beurteilen

4

Einzelne Fehlschläge → einzeln erneut versuchen

extract_text_umi_v2(path, confidence_threshold=0.65)

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 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