Skip to main content
Glama

PaddleOCR MCP Server

English

License: MIT PaddleOCR: Apache 2.0 Python 3.10-3.13 MCP SDK v2

本地运行的 PaddleOCR MCP Server,支持快速 OCR、文档结构解析、自动路由和 GPU/CPU 自动检测。

⚡ 一键安装(复制给你的 Agent)

把下面这段话直接发给任何 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: Mistral OCR MCP Server

特性

特性

说明

双模型

PP-OCRv6 快速文字识别 + PaddleOCR-VL 文档结构解析

自动路由

PDF、大图自动使用 PaddleOCR-VL,普通图片使用 PP-OCRv6

GPU 自动检测

检测 CUDA 可用性,自动使用 GPU 或回退 CPU

自动安装器

python install.py --device auto 自动选择已验证的 CPU/GPU 依赖

本地推理

图片不会上传到公共 OCR API,不需要云端 API Key

MCP SDK v2

使用 MCPServer@mcp.tool() 和结构化结果

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。

CPU 安装

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;镜像地址可能随时变化,不建议写入自动化脚本。

GPU 支持(可选)

推荐使用自动安装器,它会读取 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 doctor

Windows PowerShell:

$env:PADDLEOCR_DEVICE = "gpu:0"
paddleocr-mcp doctor

直接运行

默认使用 MCP stdio 传输:

paddleocr-mcp

也可以使用 MCP CLI:

mcp run paddleocr_mcp_server.py

其他 MCP 客户端

任何支持 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,以免加载到错误的依赖环境。

Hermes Agent 集成

安装 MCP Server 后,必须重启 Hermes Gateway 或 CLI profile 才能加载新工具。

Gateway 模式(systemd 守护进程)

在全局配置 ~/.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 级配置。

CLI 模式

~/.hermes/profiles/<your-profile>/config.yaml 添加同样的 mcp_servers 配置,然后重启 Hermes。

🤖 Agent Skill

项目附带中文版 Agent Skill 和英文版 Agent Skill,帮助 Agent 判断何时调用 OCR、选择哪个工具、处理结构化结果和错误。

Skill 能做什么

  • 用户发送图片并要求提取文字时触发;

  • 用户要求解析 PDF、表格或复杂文档时触发;

  • ocr_imageparse_documentsmart_ocr 之间选择;

  • 根据 PDF、大图和普通图片执行路由;

  • 解释置信度、Markdown 结果和失败原因。

安装到 Hermes

# 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 更稳定地选择工具并解释结果。

MCP Tools

ocr_image — 快速 OCR

适合简单文字提取:

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

language 默认是 ch,也可使用 enjapankoreanfrgerman 等 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 可设置为 ocrvl

环境变量

变量

默认值

说明

PADDLEOCR_DEVICE

自动检测

cpugpugpu:0

PADDLEOCR_VL_TIMEOUT

300

PaddleOCR-VL 超时时间(秒)

PADDLEOCR_MAX_FILE_SIZE

52428800

最大输入文件大小,默认 50 MB

PADDLEOCR_MAX_IMAGE_SIZE

1920

OCR 预处理最大边长

PADDLEOCR_ALLOWED_ROOTS

未设置

HTTP 模式建议限制可读取目录

MCP_TRANSPORT

stdio

stdiostreamable-http

MCP_HOST

127.0.0.1

HTTP 监听地址

MCP_PORT

8000

HTTP 监听端口

HTTP 只应在明确需要时启用,并由外部网络层负责认证。默认 stdio 模式不会打开网络端口。

CPU 兼容性(OneDNN)

部分旧款或非 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 遵循各自许可证。

感谢 PaddleOCRModel Context Protocoltrotsky1997/PaddleOCR-MCP 的工作与参考。

A
license - permissive license
-
quality - not tested
B
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • A
    license
    -
    quality
    D
    maintenance
    An MCP server that provides OCR capabilities using the EasyOCR library, supporting over 80 languages and GPU acceleration. It enables processing images from base64 strings, local files, or URLs with options for text-only or detailed coordinate and confidence output.
    2
    Apache 2.0
  • A
    license
    -
    quality
    B
    maintenance
    Local MCP server that provides multi-modal vision capabilities to single-modal base models via API, supporting multi-turn iterative image recognition and document image parsing.
    5
    Apache 2.0

View all related MCP servers

Related MCP Connectors

  • OCR, transcription, file extraction, and image generation for AI agents via MCP.

  • OCR.space MCP — wraps the OCR.space API (ocr.space) for image/PDF → text OCR.

  • MCP server for MiniMax H3 multimodal video generation

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Nicvank/paddleocr-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server