paddleocr-mcp

PaddleOCR MCP Skill

English version

这是本地 PaddleOCR MCP Server 的 Agent 使用指南。服务使用 MCP Python SDK v2，图片和文档在服务所在机器上处理，不调用公共 OCR API。

前置条件

• MCP Server 已安装并配置到 Agent 客户端；
• 推荐使用项目虚拟环境中的 Python；
• 推荐在安装阶段运行 python install.py --device auto，它会检测 nvidia-smi 并选择受支持的 CPU/GPU 依赖；
• paddleocr-mcp doctor 可以检查 Python、依赖、设备和模型缓存；
• 首次调用可能下载模型权重到 ~/.paddlex/official_models/。

安装器当前支持 CUDA 11.8、12.6–12.8、12.9+（12.x）和 13.x 的官方 wheel 映射；未知版本在自动模式下回退 CPU，在强制 GPU 模式下报错。

可用工具

ocr_image

使用当前安装的 PaddleOCR 默认 OCR 管线（当前依赖线为 PP-OCRv6）处理普通图片。

参数：

{
  "image_path": "/absolute/path/to/image.png",
  "language": "ch"
}

• image_path：必填，本地 PNG/JPEG/BMP/WebP/TIFF 路径；
• language：可选，默认 ch，也可使用 en、japan、korean、fr、german 等 PaddleOCR 支持的语言。

返回结构：

{
  "engine": "PP-OCRv6 (latest installed PaddleOCR)",
  "source_name": "image.png",
  "elapsed_seconds": 1.234,
  "text": "recognized text",
  "blocks": [
    {"text": "recognized text", "score": 0.998, "bbox": [10, 20, 200, 60]}
  ]
}

适合截图、照片、发票、收据和简单布局的图片。

parse_document

使用当前安装的 PaddleOCR-VL 管线处理图片或 PDF，并返回结构化 Markdown。

参数：

{
  "image_path": "/absolute/path/to/document.pdf"
}

返回结构：

{
  "engine": "PaddleOCR-VL (latest installed PaddleOCR)",
  "source_name": "document.pdf",
  "elapsed_seconds": 12.345,
  "markdown": "# Document\n\n..."
}

适合 PDF、表格、多栏文档、复杂布局和需要保留结构的任务。它比 ocr_image 更慢、更占内存。

smart_ocr

自动选择 OCR 或文档解析管线：

{
  "image_path": "/absolute/path/to/file",
  "language": "ch",
  "force_model": "ocr"
}

路由规则：

force_model == "vl"       -> parse_document
force_model == "ocr"      -> ocr_image（仅适用于图片）
PDF                         -> parse_document
图片任一边 > 2000 像素     -> parse_document
其他图片                   -> ocr_image

如果用户不确定输入类型，优先使用 smart_ocr。

Agent 决策规则

用户要求处理图片、截图、PDF 或文档
  |
  +-- 用户明确要求快速提取文字？
  |     +-- 是 -> ocr_image（普通图片）
  |     +-- 否
  |
  +-- 用户明确要求表格、版面、PDF 或 Markdown？
  |     +-- 是 -> parse_document
  |     +-- 否
  |
  +-- 输入类型或复杂度不确定？
        +-- 是 -> smart_ocr