Provides OCR capabilities for Hermes AI agents, allowing them to extract text from images (PP-OCRv6) and parse complex document structures (VL-1.6) with automatic model routing and GPU detection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@paddleocr-mcp extract text from this receipt image"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
本地运行的 PaddleOCR MCP Server，支持快速 OCR、文档结构解析、自动路由和 GPU/CPU 自动检测。
把下面这段话直接发给任何 AI Agent，它可以自动完成安装、配置和验证。
请帮我安装 paddleocr-mcp（https://github.com/Nicvank/paddleocr-mcp）。
这是一个完全本地运行的 OCR MCP 服务，使用 PP-OCRv6 进行快速文字提取，
使用 PaddleOCR-VL 进行复杂文档结构解析，并根据输入自动选择模型。
请按以下步骤操作：
1. git clone https://github.com/Nicvank/paddleocr-mcp.git ~/paddleocr-mcp
2. 检查 Python 版本，需要 Python 3.10-3.13；如果不满足，请先安装兼容版本
3. 创建虚拟环境，并运行自动安装器：
cd ~/paddleocr-mcp
python -m venv .venv
.venv/bin/python install.py --device auto
Windows 请使用 .venv\Scripts\python.exe 替代 .venv/bin/python
安装器会检测 nvidia-smi/CUDA；检测到受支持 GPU 时安装 GPU wheel，否则安装 CPU wheel
4. 将 MCP Server 配置到我的 Agent 客户端：
command: ~/paddleocr-mcp/.venv/bin/python
args: ["~/paddleocr-mcp/paddleocr_mcp_server.py"]
timeout: 600
Windows 请将 command 和 args 改成对应的绝对路径
5. 阅读 ~/paddleocr-mcp/skill/SKILL.md，并按当前 Agent 平台加载 Skill
6. 运行 doctor 检查依赖和设备；如果模型尚未下载，首次调用时等待它自动下载
7. 重启 Agent 后告诉用户：“请发一张图片给我，我来测试 OCR 是否正常工作”
如果任何步骤失败，请报告完整错误并修复。完成后告诉我安装和测试结果。Related MCP server: MCP OCR Server
特性 | 说明 |
双模型 | PP-OCRv6 快速文字识别 + PaddleOCR-VL 文档结构解析 |
自动路由 | PDF、大图自动使用 PaddleOCR-VL，普通图片使用 PP-OCRv6 |
GPU 自动检测 | 检测 CUDA 可用性，自动使用 GPU 或回退 CPU |
自动安装器 |
|
本地推理 | 图片不会上传到公共 OCR API，不需要云端 API Key |
MCP SDK v2 | 使用 |
Agent Skill | 附带 Skill，帮助 Agent 选择工具并处理 OCR 结果 |
Hermes 集成 | 支持 Gateway 和 CLI profile 配置 |
下表中的速度是原项目 CPU 基准，仅供参考；实际速度取决于图片尺寸、语言、CPU/GPU 和首次模型加载时间。
模型 | 用途 | 原有 CPU 参考 | GPU 参考 | 最佳场景 |
PP-OCRv6 | 快速文字提取 | 约 12–18 秒 | 约 1–2 秒 | 截图、照片、发票、收据 |
PaddleOCR-VL | 文档结构解析 | 约 30–120 秒 | 约 5–15 秒 | 复杂布局、表格、多栏文档、PDF |
硬件建议：
纯 CPU：任何合适的 x86_64 处理器都可以运行，适合低频使用；
GPU 加速：建议 NVIDIA CUDA 显卡和至少 6 GB 显存，适合高频或实时场景；
GPU 版本必须根据 CUDA、操作系统和 Python 版本，按照 PaddlePaddle 官方安装指南选择，不能与 CPU wheel 同时安装。
首次使用 PaddleOCR-VL 时会自动下载模型文件，可能需要数百 MB 和数分钟。模型通常缓存于
~/.paddlex/official_models/，后续调用不会重复下载。
Python 3.10–3.13；
CPU 安装使用 PaddlePaddle 3.3.1；
PaddleOCR 3.7.0；
MCP Python SDK v2。
git clone https://github.com/Nicvank/paddleocr-mcp.git
cd paddleocr-mcp
python -m venv .venv推荐直接让安装器自动判断：
python install.py --device auto如需强制 CPU：
Linux/macOS：
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[cpu]"Windows PowerShell：
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[cpu]"首次安装和首次模型调用都可能需要下载较大的依赖或模型文件，请耐心等待。
中国大陆用户如果 PyPI 下载超时，可以尝试镜像：
python -m pip install -e ".[cpu]" -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple如果 GitHub clone 失败，请优先检查网络或使用 GitHub CLI；镜像地址可能随时变化，不建议写入自动化脚本。
推荐使用自动安装器，它会读取 nvidia-smi 报告的 CUDA 版本，并从 Paddle 官方 wheel 源选择已验证的 GPU 组合：
python install.py --device auto当前自动映射为：CUDA 11.8 → cu118；CUDA 12.6–12.8 → cu126；CUDA 12.9 及更高的 12.x → cu129；CUDA 13.x → cu130。不在这些范围内时，auto 安全回退 CPU，--device gpu 则直接报错。
也可以强制要求 GPU；如果 CUDA 版本没有经过脚本映射，会直接报错而不会偷偷安装 CPU 版：
python install.py --device gpu如果机器的 CUDA 版本暂不在自动映射表中，请按照 PaddlePaddle 官方安装指南手动安装匹配的 GPU wheel。CPU 和 GPU wheel 不能同时存在。安装后验证：
python -c "import paddle; print(paddle.is_compiled_with_cuda())"运行时也可以指定推理设备：
PADDLEOCR_DEVICE=gpu:0 paddleocr-mcp doctorWindows PowerShell：
$env:PADDLEOCR_DEVICE = "gpu:0"
paddleocr-mcp doctor默认使用 MCP stdio 传输：
paddleocr-mcp也可以使用 MCP CLI：
mcp run paddleocr_mcp_server.py任何支持 MCP stdio 传输的客户端都可以连接。Windows 配置示例：
{
"mcpServers": {
"paddleocr": {
"command": "C:\\path\\to\\paddleocr-mcp\\.venv\\Scripts\\python.exe",
"args": ["C:\\path\\to\\paddleocr-mcp\\paddleocr_mcp_server.py"],
"timeout": 600
}
}
}Linux/macOS 将 command 改成 .venv/bin/python，并将 args 改成服务器文件的绝对路径。不要在配置中使用系统 Python，以免加载到错误的依赖环境。
安装 MCP Server 后，必须重启 Hermes Gateway 或 CLI profile 才能加载新工具。
在全局配置 ~/.hermes/config.yaml 添加：
mcp_servers:
paddleocr:
command: /path/to/paddleocr-mcp/.venv/bin/python
args:
- /path/to/paddleocr-mcp/paddleocr_mcp_server.py
timeout: 600
connect_timeout: 120注意：args 必须是 YAML 列表格式。Gateway 模式读取 $HERMES_HOME/config.yaml，通常是 ~/.hermes/config.yaml，不是 profile 级配置。
在 ~/.hermes/profiles/<your-profile>/config.yaml 添加同样的 mcp_servers 配置，然后重启 Hermes。
项目附带中文版 Agent Skill 和英文版 Agent Skill，帮助 Agent 判断何时调用 OCR、选择哪个工具、处理结构化结果和错误。
用户发送图片并要求提取文字时触发；
用户要求解析 PDF、表格或复杂文档时触发；
在 ocr_image、parse_document 和 smart_ocr 之间选择；
根据 PDF、大图和普通图片执行路由；
解释置信度、Markdown 结果和失败原因。
# Gateway 模式
cp -r skill/ ~/.hermes/skills/paddleocr-mcp/
# CLI profile 模式
cp -r skill/ ~/.hermes/profiles/<your-profile>/skills/media/paddleocr-mcp/
# 推荐：使用符号链接，方便随仓库更新
ln -s /path/to/paddleocr-mcp/skill ~/.hermes/skills/paddleocr-mcp即使不安装 Skill，只要 MCP Server 已配置，Agent 仍可以直接调用工具；Skill 的作用是让 Agent 更稳定地选择工具并解释结果。
ocr_image — 快速 OCR适合简单文字提取：
{
"image_path": "/path/to/image.png",
"language": "ch"
}language 默认是 ch，也可使用 en、japan、korean、fr、german 等 PaddleOCR 支持的语言。
parse_document — 文档解析适合复杂文档和 PDF：
{
"image_path": "/path/to/document.pdf"
}返回结构化 Markdown。模型异常会作为 MCP tool error 返回，而不是伪装成成功文本。
smart_ocr — 自动路由{
"image_path": "/path/to/file",
"language": "ch",
"force_model": "ocr"
}路由规则：PDF → PaddleOCR-VL；图片任一边大于 2000 像素 → PaddleOCR-VL；其他 → PP-OCRv6；force_model 可设置为 ocr 或 vl。
变量 | 默认值 | 说明 |
| 自动检测 |
|
|
| PaddleOCR-VL 超时时间（秒） |
|
| 最大输入文件大小，默认 50 MB |
|
| OCR 预处理最大边长 |
| 未设置 | HTTP 模式建议限制可读取目录 |
|
|
|
|
| HTTP 监听地址 |
|
| HTTP 监听端口 |
HTTP 只应在明确需要时启用，并由外部网络层负责认证。默认 stdio 模式不会打开网络端口。
部分旧款或非 Intel CPU 上，PaddlePaddle OneDNN 后端可能与 PIR 推理引擎冲突，出现：
NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support服务器默认使用 enable_mkldnn=False 规避常见问题。如仍遇到错误，可以设置：
export FLAGS_use_mkldnn=0或者在 MCP 配置中添加：
env:
FLAGS_use_mkldnn: "0"# 诊断 Python、依赖、设备和模型缓存
paddleocr-mcp doctor
# 安装开发依赖并运行测试
python -m pip install -e ".[dev]"
python -m pytest -q
# 手动加载 OCR 模型
python test_quick.py项目结构：
paddleocr-mcp/
├── paddleocr_mcp_server.py # MCP Server 主程序
├── install.py # CPU/GPU 自动安装器
├── pyproject.toml # 项目和依赖配置
├── skill/SKILL.md # 中文 Agent Skill
├── skill/SKILL.en.md # English Agent Skill
├── tests/test_tools.py # 工具单元测试
├── tests/test_installer.py # 安装器选择逻辑测试
├── test_quick.py # 手动模型加载测试
├── test_mcp.py # MCP 协议测试
├── AUDIT-REPORT.md # 审计和升级记录
├── LICENSE
└── README.md / README.en.md本项目使用 MIT License。PaddleOCR、PaddleX、PaddlePaddle 和 MCP SDK 遵循各自许可证。
感谢 PaddleOCR、Model Context Protocol 和 trotsky1997/PaddleOCR-MCP 的工作与参考。
Run the latest local PaddleOCR text-recognition pipeline on an image.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | ch | |
| image_path | Yes |
| Name | Required | Description |
|---|---|---|
| text | Yes | |
| blocks | No | |
| engine | Yes | |
| source_name | Yes | |
| elapsed_seconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the pipeline is local and uses PaddleOCR, but does not disclose side effects, output behavior, performance considerations, or whether the image must be a local path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It is concise, but the terseness leaves out important operational details that an agent would need.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters and an output schema exists, but the description still lacks usage guidance and parameter semantics. An agent cannot confidently choose this tool over smart_ocr or know what language values are supported.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not add meaning to either parameter. It never mentions image_path as the required input or explain the language parameter's default or supported values. The description fails to compensate for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Run the latest local PaddleOCR text-recognition pipeline on an image.' This clearly communicates the core action and object. However, it does not distinguish this tool from siblings like smart_ocr or parse_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use ocr_image versus parse_document or smart_ocr. There are no exclusions, prerequisites, or contextual signals to help an agent choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the latest local PaddleOCR-VL pipeline on an image or PDF.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes |
| Name | Required | Description |
|---|---|---|
| engine | Yes | |
| markdown | Yes | |
| source_name | Yes | |
| elapsed_seconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It only says a pipeline is 'run' and gives no indication of side effects, local model requirements, or failure behavior; 'local' is the only behavioral trait disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. 'Latest' and 'local' are somewhat vague, but the core message is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and an output schema present, the description could be minimal, but it still omits path semantics and any guidance relative to sibling OCR tools. The 'latest' qualifier is not actionable, and the description does not fully equip an agent to invoke the tool correctly in ambiguous cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter image_path has 0% schema description coverage, and the description partially compensates by saying the pipeline operates on an image or PDF. However, it does not explicitly state that image_path accepts a PDF path, what path formats are supported, or whether the file must be local.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific action ('Run the latest local PaddleOCR-VL pipeline') and target inputs ('image or PDF'), making the core function clear. It does not explicitly differentiate itself from sibling tools ocr_image and smart_ocr, which weakens clarity in this tool family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to choose parse_document over ocr_image or smart_ocr, and no exclusions are stated. The phrase 'latest local' hints at a version or environment preference but does not provide an actionable decision criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Route simple images to OCR and PDFs/large images to PaddleOCR-VL.
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | ch | |
| image_path | Yes | ||
| force_model | No |
| Name | Required | Description |
|---|---|---|
| text | No | |
| blocks | No | |
| markdown | No | |
| routed_to | Yes | |
| source_name | Yes | |
| elapsed_seconds | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of explaining behavior. It discloses the core routing behavior, but it does not explain what happens for unsupported inputs, how the 'simple' vs 'large' distinction is determined, or whether force_model overrides the routing logic. Some behavioral context is present but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no redundant words. It earns its place, though the extreme brevity leaves room for important missing details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema exists, the description is insufficient for reliable invocation: it does not clarify parameter semantics, the threshold for 'simple' vs 'large', the role of force_model, or how this tool relates to the sibling tools. An agent would need to guess at key invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters. image_path, language, and force_model are all left entirely to the agent to infer from their bare names and the generic routing statement. This is a significant gap for a tool with three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Route' and names two concrete OCR destinations, making it clear this tool selects between standard OCR and PaddleOCR-VL based on input characteristics. However, 'simple images' is vague and does not fully differentiate it from sibling tools like ocr_image or parse_document without more context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: use standard OCR for simple images, and PaddleOCR-VL for PDFs/large images. There is no explicit when-not-to-use guidance or mention of sibling alternatives, which keeps it slightly below a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0ocr_imageparse_documentsmart_ocrScored across 3 tools
ocr_image and parse_document both accept images, and smart_ocr is a routing wrapper that overlaps both. The descriptions help somewhat, but an agent cannot clearly determine whether to call smart_ocr or the specific pipeline for a given input.
ocr_image and parse_document follow a verb_noun pattern, but smart_ocr is an adjective_noun exception. The naming is readable and consistently lowercased with underscores, yet the verb styles are mixed.
Three tools is a reasonable size for an OCR-focused server. The count is not excessive, though smart_ocr makes the set feel slightly redundant since it wraps the other two tools.
The set covers basic image OCR, document-level parsing, and PDF handling, which matches the apparent domain. Minor gaps exist around configuration options like language selection or output formatting, but core workflows are supported.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server for Qwen Image 3 AI image generation
