Umi-OCR MCP Server

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

前置要求

依赖	说明
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	拼接为完整文档	按文件名排序合并

适用：按页扫描后存为多张图片的整本教材、多页试卷合集。