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

其他电脑部署

  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

批量

一次调用处理多图

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 多张本地图片,一次调用返回所有结果。

参数:
  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 已内置 3 个 Prompt,覆盖最常用的 OCR 场景。

在 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 读取后按步骤调用对应的 Tool 完成实际 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)

适用:截图、单张试卷照片、板书拍照。


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