# PaddleOCR MCP Server

[English](README.en.md)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PaddleOCR: Apache 2.0](https://img.shields.io/badge/PaddleOCR-Apache%202.0-blue.svg)](https://github.com/PaddlePaddle/PaddleOCR/blob/main/LICENSE)
[![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](https://www.python.org/downloads/)
[![MCP SDK v2](https://img.shields.io/badge/MCP-SDK%20v2-green.svg)](https://py.sdk.modelcontextprotocol.io/migration/)

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

## ⚡ 一键安装（复制给你的 Agent）

> 把下面这段话直接发给任何 AI Agent，它可以自动完成安装、配置和验证。

```text
请帮我安装 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 是否正常工作”

如果任何步骤失败，请报告完整错误并修复。完成后告诉我安装和测试结果。
```

## 特性

| 特性 | 说明 |
|------|------|
| **双模型** | 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 官方安装指南](https://www.paddlepaddle.org.cn/install/quick)选择，不能与 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 安装

```bash
git clone https://github.com/Nicvank/paddleocr-mcp.git
cd paddleocr-mcp
python -m venv .venv
```

推荐直接让安装器自动判断：

```bash
python install.py --device auto
```

如需强制 CPU：

Linux/macOS：

```bash
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[cpu]"
```

Windows PowerShell：

```powershell
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[cpu]"
```

首次安装和首次模型调用都可能需要下载较大的依赖或模型文件，请耐心等待。

中国大陆用户如果 PyPI 下载超时，可以尝试镜像：

```bash
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 组合：

```bash
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 版：

```bash
python install.py --device gpu
```

如果机器的 CUDA 版本暂不在自动映射表中，请按照 [PaddlePaddle 官方安装指南](https://www.paddlepaddle.org.cn/install/quick)手动安装匹配的 GPU wheel。CPU 和 GPU wheel 不能同时存在。安装后验证：

```bash
python -c "import paddle; print(paddle.is_compiled_with_cuda())"
```

运行时也可以指定推理设备：

```bash
PADDLEOCR_DEVICE=gpu:0 paddleocr-mcp doctor
```

Windows PowerShell：

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

### 直接运行

默认使用 MCP stdio 传输：

```bash
paddleocr-mcp
```

也可以使用 MCP CLI：

```bash
mcp run paddleocr_mcp_server.py
```

### 其他 MCP 客户端

任何支持 MCP stdio 传输的客户端都可以连接。Windows 配置示例：

```json
{
  "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` 添加：

```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](skill/SKILL.md) 和英文版 [Agent Skill](skill/SKILL.en.md)，帮助 Agent 判断何时调用 OCR、选择哪个工具、处理结构化结果和错误。

### Skill 能做什么

- 用户发送图片并要求提取文字时触发；
- 用户要求解析 PDF、表格或复杂文档时触发；
- 在 `ocr_image`、`parse_document` 和 `smart_ocr` 之间选择；
- 根据 PDF、大图和普通图片执行路由；
- 解释置信度、Markdown 结果和失败原因。

### 安装到 Hermes

```bash
# 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

适合简单文字提取：

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

`language` 默认是 `ch`，也可使用 `en`、`japan`、`korean`、`fr`、`german` 等 PaddleOCR 支持的语言。

### `parse_document` — 文档解析

适合复杂文档和 PDF：

```json
{
  "image_path": "/path/to/document.pdf"
}
```

返回结构化 Markdown。模型异常会作为 MCP tool error 返回，而不是伪装成成功文本。

### `smart_ocr` — 自动路由

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

路由规则：PDF → PaddleOCR-VL；图片任一边大于 2000 像素 → PaddleOCR-VL；其他 → PP-OCRv6；`force_model` 可设置为 `ocr` 或 `vl`。

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PADDLEOCR_DEVICE` | 自动检测 | `cpu`、`gpu` 或 `gpu: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` | `stdio` 或 `streamable-http` |
| `MCP_HOST` | `127.0.0.1` | HTTP 监听地址 |
| `MCP_PORT` | `8000` | HTTP 监听端口 |

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

## CPU 兼容性（OneDNN）

部分旧款或非 Intel CPU 上，PaddlePaddle OneDNN 后端可能与 PIR 推理引擎冲突，出现：

```text
NotImplementedError: ConvertPirAttribute2RuntimeAttribute not support
```

服务器默认使用 `enable_mkldnn=False` 规避常见问题。如仍遇到错误，可以设置：

```bash
export FLAGS_use_mkldnn=0
```

或者在 MCP 配置中添加：

```yaml
env:
  FLAGS_use_mkldnn: "0"
```

## 诊断、测试和项目结构

```bash
# 诊断 Python、依赖、设备和模型缓存
paddleocr-mcp doctor

# 安装开发依赖并运行测试
python -m pip install -e ".[dev]"
python -m pytest -q

# 手动加载 OCR 模型
python test_quick.py
```

项目结构：

```text
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](LICENSE)。PaddleOCR、PaddleX、PaddlePaddle 和 MCP SDK 遵循各自许可证。

感谢 [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)、[Model Context Protocol](https://modelcontextprotocol.io) 和 [trotsky1997/PaddleOCR-MCP](https://github.com/trotsky1997/PaddleOCR-MCP) 的工作与参考。