Umi-OCR MCP Server
Umi-OCR MCP Server
Предоставляет локальные возможности 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.mdRelated MCP server: Vision MCP
Предварительные требования
Зависимость | Описание |
Umi-OCR v2.1.5+ | Скачайте версию Paddle (рекомендуется) с umi-ocr.com, после установки включите HTTP API (Настройки -> Сервис -> Включить HTTP API, порт по умолчанию 1224) |
Python 3.11+ | Рекомендуется управлять через uv |
uv | Менеджер пакетов, используется для автоматической установки зависимостей через |
Быстрый старт
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
Развёртывание на другом компьютере
Установите uv
Установите Umi-OCR (скачайте версию Paddle с umi-ocr.com) и включите HTTP API (порт 1224)
Измените пути по умолчанию в
config.yamlиserver.pyУбедитесь, что порт 1224 не занят
При первом
uv runпотребуется интернет для автоматической загрузки зависимостей
Справочник API
Обзор инструментов
Инструмент | Назначение | Категория | Особенности токенов |
| Минимальный статус сервиса | Проверка | Вывод всего ~5 символов |
| Полный статус сервиса | Проверка | Вывод ~200 символов |
| OCR одной картинки | Основной | Стандартный вывод |
| OCR напрямую из Base64 | Основной | Без шага записи файла |
| Пакетный OCR нескольких картинок | Пакетный | Один вызов обрабатывает несколько изображений |
| Пакетный OCR по каталогу | Пакетный | Без list + построения списка |
| OCR одной страницы 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 | Проверить, что сервис онлайн |
|
2 | Извлечь текст |
|
3 | Качество низкое → повторить с меньшим порогом |
|
Применение: скриншоты, фото одного экзаменационного листа, фото доски с записями.
ocr-workflow-pdf
Стандартный процесс постраничного OCR PDF.
Шаг | Действие | Инструмент |
1 | Проверить, что сервис онлайн |
|
2 | OCR первой страницы для проверки качества |
|
3 | Текст размыт → повысить DPI до 300 |
|
4 | Много пропущенных символов → снизить порог до 0.70 |
|
5 | Качество OK → извлекать постранично | Цикл |
Применение: сканированные PDF с заданиями ЕГЭ, электронные учебные пособия, научные статьи.
ocr-workflow-batch
Стандартный процесс пакетного OCR целого учебного пособия/набора экзаменационных листов.
Шаг | Действие | Инструмент |
1 | Проверить, что сервис онлайн |
|
2 | Сканировать все изображения в каталоге |
|
3 | Выборочно проверить 2–3 результата | Вручную или силами агента оценить качество |
4 | Отдельные сбои → повторить по одному |
|
5 | Собрать в полный документ | Объединить, отсортировав по именам файлов |
Применение: целые учебники, отсканированные постранично в несколько изображений, сборники многостраничных экзаменационных листов.
Available Tools
7 toolscheck_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
Scored across 7 tools
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 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.
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.
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
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables analysis of local images through Kimi (Moonshot AI) vision models via the MCP protocol, supporting features like OCR and long context understanding.760 npmMIT
- AlicenseAqualityCmaintenanceEnables 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.227 npmMIT
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP stdio server that enables LLM agents to invoke the MiMo Vision model for local image understanding and OCR via the OpenCode API.MIT
- AlicenseNot gradedqualityDmaintenanceA 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 npmMIT