Skip to main content
Glama

Umi-OCR MCP Server

简体中文 | English

Предоставляет локальные возможности OCR Umi-OCR v2 AI-агентам (Hermes, Claude Code, Codex и др.) через протокол MCP.

Автоматически запускает процесс 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+

Скачайте версию Paddle (рекомендуется) с umi-ocr.com, после установки включите 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 с секцией mcp_servers в config.yaml Hermes:

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 возвращает код ошибки

Формат API Umi-OCR v2:

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 (скачайте версию Paddle с umi-ocr.com) и включите HTTP API (порт 1224)

  3. Измените пути по умолчанию в config.yaml и server.py

  4. Убедитесь, что порт 1224 не занят

  5. При первом uv run потребуется интернет для автоматической загрузки зависимостей

Справочник API

Обзор инструментов

Инструмент

Назначение

Категория

Особенности токенов

quick_ocr_status

Минимальный статус сервиса

Проверка

Вывод всего ~5 символов

check_ocr_status

Полный статус сервиса

Проверка

Вывод ~200 символов

extract_text_umi_v2

OCR одной картинки

Основной

Стандартный вывод

ocr_image_base64

OCR напрямую из Base64

Основной

Без шага записи файла

ocr_batch

Пакетный OCR нескольких картинок

Пакетный

Один вызов обрабатывает несколько изображений

ocr_directory

Пакетный OCR по каталогу

Пакетный

Без list + построения списка

ocr_pdf_page

OCR одной страницы PDF напрямую

PDF

Без рендеринга + сохранения файла

quick_ocr_status

Минимальная проверка статуса, подходит для высокочастотного опроса.

参数:
  无

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

Сравнение токенов: ~5 символов против ~200 символов у check_ocr_status — экономия 97%.

check_ocr_status

Полная информация о статусе сервиса.

参数:
  无

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

extract_text_umi_v2

Извлекает текст из локального изображения. Встроенное объединение абзацев и фильтрация по уверенности.

参数:
  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 — предопределённые шаблоны фиксированных инструкций. Агент вызывает их через специальный инструмент 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 возвращают текст инструкций (не результат выполнения). Агент читает их и по шагам вызывает соответствующие инструменты для фактического выполнения 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

Стандартный процесс постраничного OCR PDF.

Шаг

Действие

Инструмент

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 результата

Вручную или силами агента оценить качество

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.
      760 npm
      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