paddleocr-mcp
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 "Install 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-mcpextract 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
本地运行的 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 |
自动安装器 |
|
本地推理 | 图片不会上传到公共 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。
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 doctorWindows 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_image、parse_document和smart_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,也可使用 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 模式不会打开网络端口。
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 遵循各自许可证。
感谢 PaddleOCR、Model Context Protocol 和 trotsky1997/PaddleOCR-MCP 的工作与参考。
This server cannot be installed
Maintenance
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
- Alicense-qualityDmaintenanceAn 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.2Apache 2.0
- Flicense-qualityDmaintenanceAn MCP server that enables Claude to perform OCR on local files using Mistral AI's document processing capabilities. It converts documents and images into markdown format for seamless analysis and interaction.
- Alicense-qualityCmaintenanceHigh-performance OCR server using native Tesseract (C++) for text extraction from images, integrable with ChatGPT Desktop and other MCP clients.13MIT
- Alicense-qualityBmaintenanceLocal 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.5Apache 2.0
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
Appeared in Searches
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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