Skip to main content
Glama

Umi-OCR MCP Server

简体中文 | English

MCP プロトコルを介して Umi-OCR v2 のローカル OCR 機能を AI Agent(Hermes、Claude Code、Codex など)に公開します。

Umi-OCR プロセスを自動起動し、手動でサービスを起動する必要はありません。

ディレクトリ構成

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

Related MCP server: Vision MCP

前提条件

依存関係

説明

Umi-OCR v2.1.5+

umi-ocr.com から Paddle 版(推奨) をダウンロードし、インストール後に HTTP API を有効にします(設定 -> サービス -> HTTP API を有効化、デフォルトポート 1224)

Python 3.11+

uv での管理を推奨

uv

パッケージマネージャー。uv run で依存関係を自動インストール

クイックスタート

1. Umi-OCR のパスを確認

デフォルトパス:YOUR_UMI_OCR_PATH\Umi-OCR.exe

異なる場合は、環境変数 UMI_OCR_EXE で指定します。

Windows の注意:パスに中国語/スペース/特殊文字が含まれる場合は、YAML と環境変数で正しくエスケープしてください。

2. MCP サービスのテスト

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

初回の uv run 実行時に pyproject.toml が自動的に読み取られ、一時的な仮想環境が作成されて mcp、requests の依存関係がインストールされます。

3. Hermes Agent への接続

config.yaml の内容を Hermes の config.yaml の mcp_servers セクションにマージします:

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"

重要:--directory 引数は uv に pyproject.toml の場所を伝えます。省略できません。省略すると uv が依存関係を見つけられず、ModuleNotFoundError が発生します。

パス形式:スラッシュ D:/path/to/ を推奨します。バックスラッシュは YAML では D:\\path\\to\\ のようにエスケープする必要があります。

動作原理

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

サービスのキープアライブ

extract_text_umi_v2 を呼び出すたびにポートが自動的に検出されます。Umi-OCR プロセスが予期せず終了した場合、次の呼び出しで自動的に再起動されるため、手動での操作は不要です。

後処理ルール

正規表現による置換を内蔵し、曖昧さのない OCR の一般的な誤りを修正します(AI の理解に影響しないものは修正しません):

元のテキスト

修正後

packspace

backspace

AMDV

AMD-V

Windows102004

Windows 10 2004

打并

打开

重新新

重新

後処理では確実に判定できる OCR ノイズのみを修正し、ルールの範囲外のものはそのまま残して AI の読解に委ねます。

よくある質問

ModuleNotFoundError: No module named 'requests'

uv run はデフォルトで隔離された環境を使用するため、グローバルパッケージが見えません。

解決策:プロジェクトには pyproject.toml が含まれています。uv run --directory <项目目录> で起動してください。uv が依存関係を自動的にインストールします。

Umi-OCR の起動タイムアウト

  • UMI_OCR_EXE のパスが正しいか確認します

  • 初回起動時、Umi-OCR は PaddleOCR モデルの読み込みが必要で、遅いマシンでは 15〜30 秒かかる場合があります

  • Umi-OCR の設定で「自動起動」または「トレイに最小化」を有効にすると、毎回の待機を回避できます

API が返すエラーコード

Umi-OCR v2 API の形式:

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

戻り値:

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

  • code=300: Base64 デコード失敗(文字列ではなく配列が渡された場合)

  • code=802: base64 フィールドが不足

別の PC へのデプロイ

  1. uv をインストールします

  2. Umi-OCR をインストールし(umi-ocr.com から Paddle 版をダウンロード)、HTTP API を有効にします(ポート 1224)

  3. config.yaml と server.py のデフォルトパスを変更します

  4. ポート 1224 が使用されていないことを確認します

  5. 初回の uv run ではネットワーク接続が必要で、依存関係が自動的にダウンロードされます

API リファレンス

ツール一覧

ツール

用途

カテゴリ

Token の特徴

quick_ocr_status

最小限のサービス状態

チェック

出力はわずか ~5 文字

check_ocr_status

完全なサービス状態

チェック

~200 文字の出力

extract_text_umi_v2

単一画像の OCR

コア

標準出力

ocr_image_base64

Base64 から直接 OCR

コア

ファイル書き込みの手順が不要

ocr_batch

複数画像のバッチ OCR

バッチ

1 回の呼び出しで複数画像を処理

ocr_directory

ディレクトリスキャンのバッチ OCR

バッチ

list + リスト作成が不要

ocr_pdf_page

PDF 単一ページの直接 OCR

PDF

レンダリング + ファイル保存の手順が不要

quick_ocr_status

最小限の状態チェック。高頻度のポーリングに適しています。

参数:
  无

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

Token 比較:~5 chars vs check_ocr_status の ~200 chars で、97% 削減。

check_ocr_status

完全なサービス状態の情報。

参数:
  无

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

extract_text_umi_v2

ローカル画像からテキストを抽出する OCR。段落の結合と信頼度フィルタリングを内蔵。

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

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

ocr_image_base64

Base64 エンコードされた画像から直接テキストを抽出し、ファイル書き込みの手順を省きます。

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

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

ocr_batch

複数のローカル画像をバッチ OCR し、1 回の呼び出しで全ての結果を返します。

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

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

ocr_directory ⭐ v1.1 で新規追加

ディレクトリ内のすべての画像をスキャンしてバッチ OCR します。再帰モードではサブディレクトリも処理できます。

参数:
  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 ⭐ v1.1 で新規追加

PDF の指定ページを直接画像としてレンダリングして OCR し、一気に完了します。PyMuPDF に依存します。

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

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

信頼度しきい値の説明

すべての OCR ツールは内部で confidence_threshold を使用して低品質の結果をフィルタリングします。 直接制御が必要な場合は、新しいツールで公開されているパラメータを使用します:

シナリオ

推奨しきい値

説明

鮮明な活字

0.90+

非常に高い精度。質優先で、不確かなものは出力しない

標準的な文書

0.85(デフォルト)

精度と再現率のバランス

スキャン版教材

0.70-0.80

紙質が一定でないため、より高い許容度が必要

手書きノート

0.60-0.75

手書き文字の認識率は元々低い

MCP 固定指示(Prompts)

MCP プロトコルは Prompts —— 事前定義された固定指示テンプレートをサポートしています。 Agent は専用ツール get_prompt(name) を呼び出して取得し、標準化されたステップバイステップのワークフロー指示を受け取ります。

server.py には最も一般的な OCR シナリオをカバーする 3 つの Prompt が組み込まれています。

Hermes での呼び出し

MCP 接続を再起動すると、Hermes は mcp__umi_ocr__get_prompt ツールを自動的に登録します。 呼び出し方法:

# 列出所有可用 Prompt
mcp__umi_ocr__list_prompts()

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

Prompts が返すのは指示テキスト(実行結果ではありません)です。Agent はそれを読み取り、手順に従って対応するツールを呼び出して実際の OCR を実行します。


ocr-workflow-quick

単一画像の高速 OCR 標準フロー。

手順

操作

ツール

1

サービスがオンラインであることを確認

quick_ocr_status

2

テキストを抽出

extract_text_umi_v2(file_path)

3

品質が不十分 → しきい値を下げて再試行

extract_text_umi_v2(..., confidence_threshold=0.65)

適用例:スクリーンショット、試験問題の写真 1 枚、板書の撮影。


ocr-workflow-pdf

PDF のページ単位 OCR 標準フロー。

手順

操作

ツール

1

サービスがオンラインであることを確認

quick_ocr_status

2

先頭ページを OCR して品質を確認

ocr_pdf_page(pdf_path, page_number=1)

3

文字がぼやける → DPI を 300 に上げる

ocr_pdf_page(..., dpi=300)

4

文字の欠落がひどい → しきい値を 0.70 に下げる

ocr_pdf_page(..., confidence_threshold=0.70)

5

品質 OK → ページごとに抽出

ocr_pdf_page(pdf_path, page_number=N) を繰り返す

適用例:スキャン版の入試過去問 PDF、電子教材、論文。


ocr-workflow-batch

教材・試験問題集全体のバッチ OCR 標準フロー。

手順

操作

ツール

1

サービスがオンラインであることを確認

quick_ocr_status

2

ディレクトリ内のすべての画像をスキャン

ocr_directory(dir, recursive=true)

3

2〜3 件の結果をスポットチェック

人間または Agent が品質を判断

4

個別に失敗 → 単独で再試行

extract_text_umi_v2(path, confidence_threshold=0.65)

5

完全なドキュメントに結合

ファイル名順にソートしてマージ

適用例:ページごとにスキャンして複数の画像として保存された教材全体、複数ページの試験問題集。

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