PaddleOCR MCP Server

将 PaddleOCR(PP-OCRv5)封装为标准的 MCP (Model Context Protocol) 服务,支持 中文、英文、日文、韩文的文本识别,可被 Claude Desktop、Cursor、Codex 等 任意 MCP 客户端调用,也可作为 Docker 镜像通过网络服务对外提供 OCR 能力。

除纯文本识别外,还集成 PP-Structure 版面分析:对含表格/标题/段落的表单或 文档,可自动还原版面结构,把图片、PDF 或办公文档(PPT/Word/Excel)中的表格直接转换为 HTML 与 Markdown 表格代码 (保留行列结构),并返回每个文本区块的坐标框(Bounding Box)。PDF 与多页文档按页逐张处理。

提供两种运行方式,均支持 HTTP(streamable-http)传输:

• Docker(推荐):镜像内置四种语言模型,构建后可完全离线运行。

• Python 本地:首次运行自动下载模型,之后同样可离线。

功能特性

• 基于官方 MCP Python SDK(FastMCP),标准 stdio 与 streamable-http 双传输。

• 每种语言独立缓存 OCR 引擎实例,首次调用懒加载、后续秒级响应。

• 图片、PDF、办公文档输入均支持本地路径、http(s) URL、data: URI、裸 base64 字符串。

• 原生 PDF 支持:PDF 交给 PaddleOCR/PaddleX 按页逐张处理(依赖 PyMuPDF), 多页结果自动合并,每个文本行/区块/表格都带 page 页码;recognize_layout 额外返回 page_count 总页数。

• 办公文档支持:Word(doc/docx)、PPT(ppt/pptx)、Excel(xls/xlsx)及 ODF 格式(odt/odp/ods)先由内置的 LibreOffice headless 转成 PDF,再走 PDF 管道。 办公文档需通过本地路径或带扩展名的 URL 提供(裸 base64 不支持,因 ZIP 容器无法靠魔数嗅探)。

• 返回每行文本、文本框坐标(Bounding Box) 与置信度。

• 版面分析(recognize_layout):基于 PP-Structure 还原标题/段落/表格/图片 等版面区块,表格输出 HTML 与 Markdown(保留行列),并按阅读顺序返回各区块坐标。

• Docker 镜像内置全部四种语言模型,构建后可完全离线运行。

Related MCP server: vision-mcp-server

支持的语言

同时接受常用别名:zh / zh-cn / chinese / cn(中文),english(英文), ja / japanese(日文),ko / kr / hangul(韩文)。

Quickstart

两种方式都默认以 HTTP 服务启动,监听 0.0.0.0:8000,MCP 端点为 http://<主机IP>:8000/mcp。

方式一:Docker(推荐)

镜像构建时会预下载四种语言模型,容器启动即可调用、无需联网。

从 Docker Hub 拉取预构建镜像

仓库提供手动触发的 构建 workflow,会在原生 runner 上并行构建 amd64 与 arm64 双架构镜像,合并为单个多架构 manifest 后发布到 Docker Hub。直接拉取即可,免去本地构建:

# 拉取镜像(自动匹配当前主机的 amd64 / arm64 架构)
docker pull pewee-live/ocr-mcp:latest

# 启动服务(仅本机访问)
docker run -d --name ocr-mcp -p 8000:8000 pewee-live/ocr-mcp:latest

pewee-live 为示例命名空间,请替换为你的 Docker Hub 用户名(需与仓库 Secrets 中的 DOCKERHUB_USERNAME 一致)。 触发方式:GitHub 仓库 → Actions → 选择 Build & Push to Docker Hub → Run workflow,按需填写镜像名、标签与是否同步打 :latest。首次使用前需在 Secrets 中配置 DOCKERHUB_USERNAME 与 DOCKERHUB_TOKEN(Access Token,非密码)。

本地构建镜像

# 构建镜像(首次会下载 paddlepaddle 与四种语言模型,约需数分钟)
docker build -t ocr-mcp:latest .

# 启动服务(仅本机访问)
docker run -d --name ocr-mcp -p 8000:8000 ocr-mcp:latest

# 如果要让局域网/其他机器通过 IP 访问,需要放开 Host 白名单:
docker run -d --name ocr-mcp -p 8000:8000 \
  -e MCP_ALLOWED_HOSTS="192.168.7.49:*,localhost:*" \
  -e MCP_ALLOWED_ORIGINS="http://192.168.7.49:*,http://localhost:*" \
  ocr-mcp:latest

# 查看日志
docker logs -f ocr-mcp

启动后,MCP 端点为 http://<容器所在主机IP>:8000/mcp。

方式二:Python 本地运行

# 安装依赖
pip install -r requirements.txt

# 以 HTTP 服务启动(仅本机访问)
MCP_TRANSPORT=streamable-http python -m ocr_mcp

# 监听所有网卡,供局域网访问(并把本机 IP 加入白名单)
MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 \
MCP_PORT=8000 \
MCP_ALLOWED_HOSTS="192.168.7.49:*,localhost:*" \
MCP_ALLOWED_ORIGINS="http://192.168.7.49:*,http://localhost:*" \
python -m ocr_mcp

Windows PowerShell 设置环境变量用 $env:MCP_TRANSPORT="streamable-http" 等, 或写成一行:$env:MCP_TRANSPORT='streamable-http'; python -m ocr_mcp。

首次运行时会自动从 Hugging Face 下载 PP-OCRv5 模型到本地缓存目录 (~/.paddlex/official_models),之后可离线使用。

切换模型:server(高精度)vs mobile(快速)

本项目内置两套 PP-OCRv5 模型,Docker 镜像构建时已同时预下载,运行时通过环境变量切换,无需重新构建镜像或联网下载:

也可混搭,例如 mobile 检测(快)+ server 识别(准),只设一个、留空另一个即可。

Docker 方式切换

镜像里两套模型都预装了,启动时通过 -e 指定即可,切换后首次调用需将模型加载进内存(数秒):

# 默认(mobile,快)— 镜像内置,直接 run
docker run -d -p 8000:8000 ocr-mcp:latest

# 切到 server(精度最高,慢)
docker run -d -p 8000:8000 \
  -e OCR_DET_MODEL=PP-OCRv5_server_det \
  -e OCR_REC_MODEL=PP-OCRv5_server_rec \
  ocr-mcp:latest

# 混搭:mobile 检测(快)+ server 识别(准)
docker run -d -p 8000:8000 \
  -e OCR_DET_MODEL=PP-OCRv5_mobile_det \
  -e OCR_REC_MODEL=PP-OCRv5_server_rec \
  ocr-mcp:latest
  
  
 # 切到mobile 
docker run -d -p 8000:8000 \
  -e OCR_DET_MODEL=PP-OCRv5_mobile_det \
  -e OCR_REC_MODEL=PP-OCRv5_mobile_rec \
  ocr-mcp:latest

Python 方式切换

Python 方式同样用 OCR_DET_MODEL / OCR_REC_MODEL,首次切换会联网下载对应模型(之后缓存):

# 默认 server(Python 不像 Docker 有预设,需手动指定,否则按 PP-OCRv5 自动选 server)
MCP_TRANSPORT=streamable-http python -m ocr_mcp

# 切到 mobile(快)
MCP_TRANSPORT=streamable-http \
OCR_DET_MODEL=PP-OCRv5_mobile_det \
OCR_REC_MODEL=PP-OCRv5_mobile_rec \
python -m ocr_mcp

# 切到 server(精度最高)
MCP_TRANSPORT=streamable-http \
OCR_DET_MODEL=PP-OCRv5_server_det \
OCR_REC_MODEL=PP-OCRv5_server_rec \
python -m ocr_mcp

Windows PowerShell: $env:OCR_DET_MODEL='PP-OCRv5_mobile_det'; $env:OCR_REC_MODEL='PP-OCRv5_mobile_rec'; python -m ocr_mcp

重要:跨机访问与 Host 白名单

MCP SDK 默认开启 DNS 重绑定防护,只放行本机地址: 127.0.0.1、localhost、[::1]。

因此,只要你是通过 IP、域名或另一台机器访问(例如 http://192.168.7.49:8000/mcp),就必须把该访问地址加入白名单, 否则请求会被拒绝并返回:

Invalid Host header   (HTTP 421)

这种情况下 MCP 客户端连不上服务,工具也不会出现在客户端里(表现为客户端 改用自带模型去"识别",而不是调用本 MCP)。

配置方法(逗号分隔,* 表示端口通配):

只在本机访问(用 localhost)时无需配置。

验证服务是否正常

MCP 采用 streamable-http 传输,是有状态的协议:必须先 initialize 握手拿到会话 ID,再发 notifications/initialized,之后才能调用工具。下面提供两种验证方式。

方式一:curl 快速握手

用 curl 做 MCP 握手,确认服务可达:

# 成功:返回 200 + 一段 JSON/SSE 流,包含 serverInfo
curl -i -X POST http://192.168.7.49:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 如果返回 "Invalid Host header"(421),说明该访问地址没加入白名单

方式二:Postman 端到端(base64)

仓库提供了可直接导入的 Postman Collection:tests/ocr-mcp.postman_collection.json,内含三个按顺序的请求,会话 ID 自动传递,无需手动复制。

第 0 步:准备 base64 图片

Postman 无法直接读取本地文件,需先把图片转成 data URI。任选一种(PDF 同理,把 image/pdf 作为 MIME 即可):

# PowerShell(Windows):输出一整行 data URI,复制备用
$b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("sample_data\zh.png"))
"data:image/png;base64,$b64"

# Python(跨平台)
python -c "import base64; b=base64.b64encode(open('sample_data/zh.png','rb').read()).decode(); print('data:image/png;base64,'+b)"

第 1 步:导入并配置

1. Postman → Import → 选择 tests/ocr-mcp.postman_collection.json。

2. 点击 Collection 名 → Variables,设置:

   • base_url:你的服务地址(如 http://192.168.137.94:8000)

   • base64_image:上一步复制的 data URI

   • session_id:留空(会自动填充)

第 2 步:按顺序发送三个请求

三个请求都是 POST {{base_url}}/mcp,必须带这两个头: Content-Type: application/json、Accept: application/json, text/event-stream。 第 2、3 个请求还要带 mcp-session-id: {{session_id}}。 Collection 已配好这些,直接 Send 即可。

第 3 步:查看结果

第 3 个请求的响应是 SSE 流,Postman 会以 EventStream 形式展示,其中 data: 后的 JSON 结构为:

{
  "jsonrpc": "2.0", "id": 2,
  "result": {
    "content": [{"type": "text", "text": "{\"language\":\"ch\",\"count\":2,\"text\":\"你好世界\nHello OCR\"}"}],
    "isError": false
  }
}

即 OCR 成功。若 isError 为 true,看 content 里的错误信息(例如跨机访问时本机路径无效,需改用 data URI 或服务端可达的 URL)。

其他:stdio 端到端测试

python tests/test_mcp_client.py

接入 MCP 客户端

Codex

编辑 Codex 配置文件(Windows:~/.codex/config.toml,即 %USERPROFILE%\.codex\config.toml):

[mcp_servers.ocr]
enabled = true
url = "http://192.168.7.49:8000/mcp"

保存后重启 Codex,即可在对话中让其"识别这张图片里的文字"。

Claude Desktop

编辑配置文件(macOS:~/Library/Application Support/Claude/claude_desktop_config.json, Windows:%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "paddleocr": {
      "url": "http://192.168.7.49:8000/mcp",
      "type": "http"
    }
  }
}

Cursor

在 Cursor 设置 → MCP 中添加 HTTP 类型的 MCP Server,URL 填 http://192.168.7.49:8000/mcp。

提供的 MCP 工具

recognize_text

对图片、PDF 或办公文档执行 OCR 文本识别。

返回示例:

{
  "language": "ch",
  "count": 2,
  "recognized_text": "你好世界\nHello OCR",
  "lines": [
    {"text": "你好世界", "box": [[25, 58], [300, 58], [300, 114], [25, 114]], "page": 0},
    {"text": "Hello OCR", "box": [[40, 120], [220, 120], [220, 154], [40, 154]], "page": 0}
  ]
}

每行 lines 始终返回,且自带坐标框 box 与 page 页码(从 0 开始);detail=true 时每行额外带 confidence。 顶层键为 recognized_text(非 text,因 Dify 保留 text 作为工作流变量名)。 box 是四点角框 [[x1,y1],[x2,y1],[x2,y2],[x1,y2]](顺时针、像素坐标,来自检测多边形); 与 recognize_layout 的 box([x1,y1,x2,y2] 四值轴对齐框)格式不同。

多页 PDF:PDF 按页逐张识别,各行带 page 页码(0 起),box 坐标基于其所在页; recognized_text 把所有页的文本按顺序换行拼接。

recognize_layout

对图片、PDF 或办公文档执行版面分析(基于 PP-Structure),还原表格/标题/段落等结构。

与 recognize_text(扁平文本行)不同,它把页面切分为多个版面区块 (title/text/table/figure/formula/...),识别表格并转为 HTML 与 Markdown (保留行列结构),同时重建阅读顺序,每个区块都带坐标框 box。

返回字段:

返回形态(flat 参数决定):

• regions:版面区块列表,每项含 {type, text, box, page},表格区块额外含 {html, markdown}。

• tables:识别到的表格列表,每项含 {html, markdown, box, cell_count, page}。

• markdown:整页 Markdown 渲染结果,表格以 Markdown 表格语法保留行列结构;多页 PDF 时各页之间以 --- 分隔。

• region_count / table_count:区块数与表格数;width/height:页面像素尺寸。

• page_count:页数(单张图片为 1,PDF 为实际页数)。

返回示例(含一张 2x2 表格的表单):

{
  "language": "ch",
  "region_count": 2,
  "table_count": 1,
  "regions": [
    {"type": "title", "text": "员工信息表", "box": [40, 20, 410, 70], "page": 0},
    {
      "type": "table", "box": [30, 90, 430, 260],
      "text": "<table><tr><td>姓名</td><td>年龄</td></tr>...</table>",
      "html": "<table><tr><td>姓名</td><td>年龄</td></tr><tr><td>张三</td><td>30</td></tr></table>",
      "markdown": "| 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 30 |"
    }
  ],
  "tables": [
    {"html": "<table>...</table>", "markdown": "| 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 30 |", "box": [30, 90, 430, 260], "cell_count": 4, "page": 0}
  ],
  "markdown": "# 员工信息表\n\n| 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 30 |"
}

上例为单页(图片或单页 PDF),故顶层 page_count 省略(为 1)。多页 PDF 时 每个 region/table 都带其所在页的 page 索引(0 起),并额外返回顶层 page_count。

box 为 [x1, y1, x2, y2](左上/右下,像素坐标,基于其所在页)。表格的 markdown 由服务端 把识别出的 HTML 表格转换而来,colspan/rowspan 会展开为重复单元格以保持网格。

引擎与子 pipeline:recognize_layout 默认启用表格/版面/文字识别。公式/图表/印章 识别仅在原生 paddle 引擎下可用(即 OCR_ENGINE 未强制 onnx、x86_64 环境)——paddlex 的这三类模型没有 onnx 包,在 onnxruntime 引擎下(aarch64 默认 / OCR_ENGINE=onnxruntime) 会被自动关闭(否则加载即报 does not provide a 'onnx' package)。设 OCR_LAYOUT_FULL=1 强制开启(仅 paddle 引擎有意义)。

list_supported_languages

返回本服务支持的语言代码与说明,无需参数。

环境变量

OCR 模型与推理相关:

Docker 镜像默认设置 MCP_TRANSPORT=streamable-http。

本地 stdio 模式

适用于 Claude Desktop、Cursor 等通过子进程接入的客户端。

# 不设置 MCP_TRANSPORT 即为 stdio
python -m ocr_mcp

Claude Desktop 配置(stdio):

{
  "mcpServers": {
    "paddleocr": {
      "command": "python",
      "args": ["-m", "ocr_mcp"],
      "cwd": "C:/develop/pythonws/ocr-server",
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

构建与测试

# 生成四种语言的测试图片(需要本机有对应字体)
python tests/make_test_image.py

# 在 Docker 容器内直接验证 OCR 引擎(中/英/日/韩)
docker run --rm \
  -v "${PWD}/tests:/work/tests" \
  -v "${PWD}/sample_data:/work/sample_data" \
  -e PYTHONPATH=/app -w /app \
  --entrypoint python ocr-mcp:latest /work/tests/test_engine.py

# 端到端 MCP 客户端测试(stdio)
python tests/test_mcp_client.py

项目结构

ocr-server/
├── ocr_mcp/
│   ├── __init__.py        # 包入口
│   ├── __main__.py        # python -m ocr_mcp 入口
│   ├── ocr_engine.py      # PaddleOCR 引擎封装与结果归一化
│   ├── server.py          # FastMCP 服务与工具定义
│   ├── layout_engine.py   # PP-Structure 版面/表格分析与 HTML→Markdown 转换
│   └── warmup.py          # 模型预下载脚本(Docker 构建期调用)
├── tests/
│   ├── make_test_image.py # 生成四语言测试图
│   ├── test_engine.py     # OCR 引擎直跑验证
│   └── test_mcp_client.py # stdio MCP 端到端验证
├── Dockerfile             # 内置模型的 Docker 镜像
├── requirements.txt       # 运行时依赖
└── pyproject.toml         # 包元数据与入口命令

实现说明

• 模型版本锁定为 PP-OCRv5:paddleocr >=3.7 在只传 lang、不传 ocr_version 时会 默认选用 PP-OCRv6(PP-OCRv6_medium_det/rec),而 PP-OCRv6 在 paddlepaddle 3.x CPU 上会触发原生段错误(ConvertPirAttribute2RuntimeAttribute),连 enable_mkldnn=False 也无法避免,直接导致进程崩溃、服务停止。本项目通过 ocr_version="PP-OCRv5" 锁定到验证可用的 v5 模型(中/英/日/韩均有对应模型)。可用环境变量 OCR_VERSION 覆盖(如 PP-OCRv4)。

• 关闭 PIR 执行器:在导入 paddle 前,默认设置 FLAGS_enable_pir_in_executor=0、 FLAGS_enable_pir_api=0,作为 CPU 段错误的兜底防御。需要恢复新 IR 执行器时设 OCR_PIR=1。

• CPU 推理:device="cpu" + enable_mkldnn=False,规避 OneDNN 相关问题。如需 GPU, 可在 ocr_engine.py 中将 device="cpu" 改为 "gpu" 并移除 enable_mkldnn=False,同时使用 GPU 版 paddlepaddle。

• 模型变体(server / mobile 两套预热):镜像构建时通过 warmup 同时预下载 server (高精度、慢)与 mobile(快 3-5 倍,适合运单等清晰印刷体)两套模型,运行时用 OCR_DET_MODEL / OCR_REC_MODEL 切换,无需重新 build 或联网下载。镜像默认 mobile。

• GPU 加速:设置 OCR_DEVICE=gpu 即可走 GPU 推理(需 GPU 版 paddlepaddle-gpu + NVIDIA 驱动 + nvidia-container-toolkit,docker run --gpus all)。aarch64(树莓派等)无 NVIDIA GPU,只能 CPU。

• ARM64(aarch64)用 ONNX Runtime:paddlepaddle 3.x 的 aarch64 预编译包在推理时存在 原生空指针段错误(native kernel,无环境变量可绕)。本项目在检测到 aarch64(树莓派、Graviton、 Apple Silicon Docker 等)时自动改用 engine='onnxruntime',完全绕开 paddle native kernel。 需要安装 onnxruntime 与 paddle2onnx(已加入 requirements)。可用 OCR_ENGINE 覆盖。

• 模型缓存:镜像构建时通过 python -m ocr_mcp.warmup 预初始化四种语言的引擎, 模型权重写入 /home/app/.paddlex/official_models,使运行期不再依赖网络。

• 线程安全:OCR 推理通过 anyio.to_thread.run_sync 在工作线程中执行,避免阻塞 MCP 事件循环;引擎实例以语言为键缓存,带双重检查锁。

• PDF 支持:PDF 直接交给 PaddleOCR/PaddleX 的 predict() 原生按页处理(内部用 PyMuPDF 解码各页),不预先栅格化。本服务仅负责:把 URL/base64 形式的 PDF 落成临时文件 再透传路径(URL/base64 无法被引擎当字节消费),并在推理后清理临时文件;本地 PDF 路径则 原样透传。多页结果按页合并,每行/区块/表格带 page,recognize_layout 额外返回 page_count, 多页 Markdown 以 --- 分页。

• 办公文档支持:Word/PPT/Excel(doc/docx/ppt/pptx/xls/xlsx/odt/odp/ods) 先由内置 LibreOffice headless 转成 PDF,再走上述 PDF 管道。每次调用用独立的 UserInstallation profile 目录,避免并发 soffice 实例争用共享锁;转换产物作为临时 PDF 追踪并由 release_input 清理。镜像需安装 LibreOffice + fonts-noto-cjk(无中文字体会渲染成豆腐块, OCR 出来是乱码)。办公文档仅支持本地路径与带扩展名的 URL(裸 base64 不支持,因 OOZIP 容器无法靠魔数嗅探)。

依赖版本

• paddleocr 3.7.0 + paddlepaddle 3.2.2(3.2.2 是最高同时有 amd64/aarch64 wheel 的版本) onnxruntime + paddle2onnx(ORT 引擎 / aarch64 推理所需) pydantic 2.13.4 + mcp 1.28.1(版本锁定,避免 pip 回溯解析失败) Python >= 3.10(镜像基于 python:3.11-slim)

License

MIT