企业官网建设流程全解析

PaddleOCR MCP Server 接入指南：把 OCR、版面解析与 VLM 文档理解能力接入大模型生态

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR

本文基于 docs/version3.x/integrations/mcp_server.en.md 编写，并结合仓库 mcp_server 源码进行实现级印证。PaddleOCR 官方提供了一个基于 FastMCP 构建的轻量级 MCP（Model Context Protocol）Server，可将文本识别、版面解析等能力以标准 MCP 工具的形式暴露给 Claude for Desktop、VSCode 等 MCP Host，让大模型应用直接调用ocr、pp_structurev3、paddleocr_vl三个工具完成图片/PDF 的识别与文档化。读完本文，你将掌握paddleocr-mcp的安装、四种推理方式（本地推理、官方 API、千帆 API、自托管 API）的配置、CLI 运行方式，以及全部环境变量/命令行参数的语义与默认值，并了解其背后的模型-工具映射、输入契约与参数校验等实现机制。

1. 核心能力总览

PaddleOCR MCP Server 将 PaddleOCR 的多种能力封装为标准 MCP 工具，供大模型应用调用。其核心价值在于：开发者无需编写任何 OCR 代码，只需在 MCP Host（如 Claude for Desktop）的配置文件中声明该 Server，大模型即可通过自然语言驱动 OCR 与文档解析任务。

1.1 支持的模型与工具映射

MCP Server 会根据所选模型自动暴露对应的工具，模型与工具的映射关系如下表（与源码 selection.py 中的_MODEL_TOOLS完全一致）：

在源码层面，模型与工具的绑定通过 tasks/factory.py 完成注册：ocr对应OCRTask，pp_structurev3对应PPStructureV3Task，paddleocr_vl对应PaddleOCRVLTask，其中后两者继承自DocParsingTask（见 tasks/doc_parsing.py），共享 Markdown 文档解析输出逻辑。

1.2 支持的推理方式

MCP Server 支持四种推理来源（InferenceProvider枚举定义于 providers.py）：

• 本地推理（local）：直接在本地机器上运行 PaddleOCR 流水线。对本地环境和硬件性能有一定要求，适用于离线使用、数据隐私要求严格的场景。
• 官方 API（aistudio）：调用 PaddleOCR 官方 API（AI Studio）。适合快速体验功能、验证方案等无代码开发场景。
• 千帆 API（qianfan）：调用百度智能云千帆平台提供的 API。
• 自托管 API（self_hosted）：调用用户自部署的 PaddleOCR 推理服务，兼具服务化优势与高灵活性，适合需要定制服务配置及数据隐私要求严格的场景。当前仅支持基础 serving 方案。

值得注意的约束：千帆来源仅支持PP-StructureV3与PaddleOCR-VL两个模型，源码在 selection.py 中以QIANFAN_SUPPORTED_MODELS常量明确限定；同时 inference/factory.py 的注册表显示，ocr工具只注册了 local / aistudio / self_hosted 三种来源（没有 qianfan），而pp_structurev3与paddleocr_vl则四种来源齐全。

1.3 典型应用示例

官方文档展示了三个创意使用场景：

• Demo 1：在 Claude for Desktop 中，从图片提取手写内容并保存到笔记软件 Notion。PaddleOCR MCP Server 负责提取文本、公式等信息并保持文档结构（该 Demo 还配合使用了 Notion MCP Server）。
• Demo 2：在 VSCode 中，将手写想法或伪代码一键转换为符合项目编码规范的可运行 Python 脚本并上传至 GitHub 仓库。PaddleOCR MCP Server 负责从图片中提取手写代码（该 Demo 还配合使用了 filesystem MCP Server）。
• Demo 3：在 Claude for Desktop 中，将包含复杂表格、公式、手写文本的 PDF 文档或图片转换为本地可编辑文件。其中 Demo 3.1 将带表格和水印的复杂 PDF 转为可编辑的 doc/Word 格式；Demo 3.2 将包含公式和表格的图片转为可编辑的 csv/Excel 格式。

2. 安装paddleocr-mcp

paddleocr-mcp需要Python 3.10 及以上版本。它默认依赖paddleocr>=3.7.0，因此使用官方 API、千帆 API 和自托管 API 三种模式时无需单独安装 PaddleOCR；本地推理则需要额外的文档解析依赖和运行 PaddleOCR 流水线所需的推理引擎（详见 4.1 方法一：本地推理）。

从 PyPI 安装：

pip install -U paddleocr-mcp

从源码安装（仓库中mcp_server即该库的独立 Python 包）：

git clone https://github.com/PaddlePaddle/PaddleOCR.git pip install -e mcp_server

从源码的 pyproject.toml 可以看到其核心依赖包括mcp>=1.5.0、fastmcp>=2.0.0、httpx>=0.24.0、numpy>=1.24.0、paddleocr>=3.7.0、pillow>=9.0.0、puremagic>=1.30.0等，并提供了两个可选依赖组：

• paddleocr-mcp[local]：包含paddleocr[doc-parser]>=3.7.0（不含推理引擎）；
• paddleocr-mcp[local-cpu]：在local基础上额外包含 CPU 版飞桨推理引擎paddlepaddle>=3.2.1。

安装完成后，可通过以下命令验证是否成功：

paddleocr_mcp --help

若命令能打印帮助信息，则说明安装成功。该命令的入口由 pyproject.toml 中的[project.scripts]声明：paddleocr_mcp = "paddleocr_mcp.__main__:main"。

此外，PaddleOCR 还支持通过uvx免安装直接运行 Server，详见 4.4 使用 uvx 免安装运行。

3. 在 Claude for Desktop 中使用

本节以 Claude for Desktop 为例说明接入流程，步骤同样适用于其他 MCP Host（仅需少量调整）。

3.1 快速开始（官方 API 示例）

以下快速开始以官方 API推理为例：

1. 安装paddleocr-mcp：参考第 2 节。

2. 获取 Access Token：在 AI Studio 的 Access Token 页面获取你的访问令牌。

3. 添加 MCP Server 配置：找到claude_desktop_config.json配置文件——

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

   打开该文件，参照下面的示例修改并填入：

   { "mcpServers": { "paddleocr": { "command": "paddleocr_mcp", "args": [], "env": { "PADDLEOCR_MCP_MODEL": "PP-OCRv5", "PADDLEOCR_MCP_PPOCR_SOURCE": "aistudio", "PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN": "<your-access-token>" } } } }

   注意事项：

   • 将<your-access-token>替换为你的访问令牌；
   • 如需使用自定义服务地址，可设置PADDLEOCR_MCP_AISTUDIO_BASE_URL环境变量。

   安全提示：

   • 切勿泄露你的access token；
   • 如果paddleocr_mcp不在系统PATH中，请将command设置为可执行文件的绝对路径。

4. 重启 MCP Host：重启 Claude for Desktop 后，paddleocrServer 即可在应用中使用。

3.2 MCP Host 配置字段详解

在 Claude for Desktop 的配置文件中，需要定义 MCP Server 的启动方式，关键字段如下：

• command：paddleocr_mcp（若可执行文件在PATH中）或可执行文件的绝对路径；
• args：可配置的命令行参数，例如["--verbose"]，详见第 6 节参数参考；
• env：可配置的环境变量，详见第 6 节参数参考。

3.3 四种推理方式的配置

3.3.1 方法一：本地推理 {#method-1-local-inference}

1. 安装paddleocr-mcp及本地推理依赖。paddleocr-mcp已依赖 PaddleOCR；本地推理额外需要文档解析依赖和推理引擎。可参考 PaddleOCR 安装指南 手动安装，或使用对应的可选依赖：

   • paddleocr-mcp[local]：包含paddleocr[doc-parser]>=3.7.0（不含推理引擎）；
   • paddleocr-mcp[local-cpu]：基于local，额外包含 CPU 版飞桨推理引擎（paddlepaddle>=3.2.1）。

   # 安装本地推理所需的文档解析依赖（不含推理引擎）： pip install "paddleocr-mcp[local]" # 在 local 基础上再安装 CPU 版飞桨框架： pip install "paddleocr-mcp[local-cpu]"

   为避免依赖冲突，强烈建议在隔离的虚拟环境中安装。

2. 参照下面的配置示例修改claude_desktop_config.json。

3. 重启 MCP Host。

配置示例：

{ "mcpServers": { "paddleocr": { "command": "paddleocr_mcp", "args": [], "env": { "PADDLEOCR_MCP_MODEL": "PP-OCRv5", "PADDLEOCR_MCP_PPOCR_SOURCE": "local" } } } }

注意事项：

• PADDLEOCR_MCP_MODEL需设置为模型名，取值见第 6 节；
• PADDLEOCR_MCP_PIPELINE_CONFIG为可选配置。若未设置，将使用默认流水线配置。如需调整配置（如更换模型），可参考 PaddleOCR 与 PaddleX 的关系说明 导出流水线配置文件，并将PADDLEOCR_MCP_PIPELINE_CONFIG设置为该文件的绝对路径。

推理性能优化建议：

如果遇到推理耗时长或内存不足的情况，可考虑调整流水线配置：

• PP-StructureV3 流水线：

  • 关闭不需要的功能，例如将use_formula_recognition设为False以关闭公式识别；
  • 使用轻量模型，例如将 OCR 模型替换为mobile版本，或切换到 PP-FormulaNet-S 等轻量公式识别模型。

  下面示例代码导出了一份关闭大部分可选功能、并将关键模型替换为轻量版本的 PP-StructureV3 流水线配置：

  from paddleocr import PPStructureV3 pipeline = PPStructureV3( use_doc_orientation_classify=False, # 关闭文档图像方向分类 use_doc_unwarping=False, # 关闭文本图像矫正 use_textline_orientation=False, # 关闭文本行方向分类 use_formula_recognition=False, # 关闭公式识别 use_seal_recognition=False, # 关闭印章文本识别 use_table_recognition=False, # 关闭表格识别 use_chart_recognition=False, # 关闭图表解析 # 使用轻量模型 text_detection_model_name="PP-OCRv5_mobile_det", text_recognition_model_name="PP-OCRv5_mobile_rec", layout_detection_model_name="PP-DocLayout-S", ) # 配置文件将保存到 `PP-StructureV3.yaml` pipeline.export_paddlex_config_to_yaml("PP-StructureV3.yaml")

  PaddleOCR-VL 系列不建议使用 CPU 推理。

从源码看，本地推理的动态参数集合定义在 inference/pp_structurev3/params.py，共 31 项，覆盖文档方向分类、矫正、文本行方向、印章识别、表格识别、公式识别、图表解析、版面检测阈值/NMS/合并模式、文本检测阈值系列、表格 HTML 转换开关、Markdown 忽略标签等，默认值中use_chart_recognition为True（见 params.py）。

3.3.2 方法二：官方 API

参考 3.1 快速开始。对于文本识别之外的任务，需正确设置PADDLEOCR_MCP_MODEL（参数细节见第 6 节）。

从源码看，官方 API 通过 paddleocr_api_sdk.py 中的异步客户端（AsyncPaddleOCRClient）完成鉴权与任务提交，并定义了AuthError、JobFailedError、RequestTimeoutError等细粒度异常类型（见 inference/ocr/aistudio.py），说明官方 API 采用异步任务轮询模型：提交任务后轮询状态，直到任务完成或超时。

3.3.3 方法三：千帆 API

1. 安装paddleocr-mcp。
2. 参考千帆平台官方文档获取 API Key。
3. 参照下面的配置示例修改claude_desktop_config.json。
4. 重启 MCP Host。

配置示例：

{ "mcpServers": { "paddleocr": { "command": "paddleocr_mcp", "args": [], "env": { "PADDLEOCR_MCP_MODEL": "PaddleOCR-VL", "PADDLEOCR_MCP_PPOCR_SOURCE": "qianfan", "PADDLEOCR_MCP_QIANFAN_API_KEY": "<your-api-key>" } } } }

注意事项：

• PADDLEOCR_MCP_MODEL需设置为模型名。千帆仅支持PP-StructureV3和PaddleOCR-VL；
• PADDLEOCR_MCP_QIANFAN_BASE_URL为千帆 API 的基础 URL（可选）；
• PADDLEOCR_MCP_QIANFAN_API_KEY是你的千帆 API Key，用于身份认证。

3.3.4 方法四：自托管 API

1. 在需要运行 PaddleOCR 推理服务器的环境中，参考 PaddleOCR serving 部署文档 启动推理服务器；
2. 在需要运行 MCP Server 的环境中安装paddleocr-mcp；
3. 参照下面的配置示例修改claude_desktop_config.json；
4. 重启 MCP Host。

配置示例：

{ "mcpServers": { "paddleocr": { "command": "paddleocr_mcp", "args": [], "env": { "PADDLEOCR_MCP_MODEL": "PP-OCRv5", "PADDLEOCR_MCP_PPOCR_SOURCE": "self_hosted", "PADDLEOCR_MCP_SELF_HOSTED_BASE_URL": "<your-server-url>" } } } }

注意事项：

• PADDLEOCR_MCP_MODEL需设置为模型名，取值见第 6 节；
• 将<your-server-url>替换为底层服务的 Base URL（例如http://127.0.0.1:8080，不要带/ocr、/layout-parsing等路径后缀，MCP 会按流水线自动拼接）。

源码印证：自托管模式通过 http_base.py 中的HTTPInferenceBase实现，各任务通过_get_endpoint()返回路径后缀（如 OCR 返回"ocr"，见 inference/ocr/self_hosted.py），这也解释了为什么配置 URL 时不能带路径后缀。同时，服务启动时会校验该 Base URL 必须存在（见main.py 的_validate_args）。

3.4 使用 uvx 免安装运行

PaddleOCR 还支持通过uvx启动 MCP Server，无需手动安装paddleocr-mcp。主要步骤如下：

1. 安装 uv；
2. 修改claude_desktop_config.json，示例如下。

自托管 API 推理示例：

{ "mcpServers": { "paddleocr": { "command": "uvx", "args": [ "--from", "paddleocr-mcp", "paddleocr_mcp" ], "env": { "PADDLEOCR_MCP_MODEL": "PP-OCRv5", "PADDLEOCR_MCP_PPOCR_SOURCE": "self_hosted", "PADDLEOCR_MCP_SELF_HOSTED_BASE_URL": "<your-server-url>" } } } }

本地推理（CPU 推理，使用local-cpu可选依赖）示例：

{ "mcpServers": { "paddleocr": { "command": "uvx", "args": [ "--from", "paddleocr-mcp[local-cpu]", "paddleocr_mcp" ], "env": { "PADDLEOCR_MCP_MODEL": "PP-OCRv5", "PADDLEOCR_MCP_PPOCR_SOURCE": "local" } } } }

本地推理依赖、性能调优与流水线配置请参考 3.3.1 方法一：本地推理。

由于启动方式不同，配置文件中的command与args与前述方式有差异，但 MCP 服务支持的命令行参数和环境变量（如PADDLEOCR_MCP_SELF_HOSTED_BASE_URL）仍可按相同方式设置。

4. 通过 CLI 运行 Server

除了 Claude for Desktop 等 MCP Host，你还可以通过 CLI 直接运行 PaddleOCR MCP Server。打印帮助信息：

paddleocr_mcp --help

常用命令示例：

# PP-OCRv5 + 官方 API + stdio PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN=xxxxxx paddleocr_mcp --model PP-OCRv5 --ppocr_source aistudio # PP-OCRv6 + 官方 API + stdio paddleocr_mcp --model PP-OCRv6 --ppocr_source aistudio # PP-StructureV3 + 本地推理 + stdio paddleocr_mcp --model PP-StructureV3 --ppocr_source local # OCR + 自托管 API + Streamable HTTP paddleocr_mcp --model PP-OCRv5 --ppocr_source self_hosted --self-hosted-base-url http://127.0.0.1:8080 --http

MCP Server 支持的全部参数见第 6 节。从源码main.py 可以还原其启动流程：async_main先解析并校验参数（模型合法性、来源所需的令牌/URL 是否齐备），随后resolve_model归一化模型名，create_inference按“模型 × 来源”组合实例化推理对象，create_task依据模型创建对应任务，最后以 FastMCP 注册工具并选择传输方式运行——--http时使用streamable-http传输（可绑定--host/--port，默认127.0.0.1:8000），否则使用默认的 stdio 传输。

5. MCP 工具调用契约与输出行为

5.1 统一输入契约

MCP 工具暴露的input_data参数支持四种形式（定义于 input_contract.py 与 input_adapters.py）：

• 绝对文件路径：MCP Server 进程可访问的绝对路径（支持~展开），相对路径会被拒绝；
• HTTP(S) URL：直接传给后端；
• 原始 Base64：按内容自动判别图片或 PDF；
• Data URL：data:前缀的 Base64 编码输入。

不同来源的适配器行为略有差异：本地推理（LocalInputAdapter）会将 Base64 图片解码为 BGR 的 numpy 数组、将 Base64 PDF 物化为临时文件；AI Studio（AIStudioInputAdapter）会把本地路径或临时文件上传为文件路径；HTTP 类来源（千帆/自托管，HTTPInputAdapter）则将文件内容编码为 Base64 后随请求提交。classify_input会依次按 URL → data URL → Base64 → 路径进行判定（input_contract.py），并支持 jpg/jpeg/png/pdf/bmp/webp/tiff/gif 等常见扩展名。

5.2 工具参数与输出格式

每个工具统一暴露以下参数（实现于 tasks/base.py 的_invoke_tool）：

• input_data：文件输入，格式取决于配置的推理来源；
• output_mode：simple输出纯文本，detailed输出 JSON；
• file_type：image或pdf，当 HTTP 类 API 无法从输入推断类型时需要显式指定；
• return_images：文档解析输出是否包含图片；
• runtime_params：可选流水线参数（JSON 对象）。

以ocr工具为例（tasks/ocr.py）：simple模式返回识别文本并附带置信度与行数摘要（如Confidence: 98.3% | 12 text lines），detailed模式返回包含text、confidence、text_lines（含 bbox 坐标）的完整 JSON。pp_structurev3与paddleocr_vl工具（tasks/doc_parsing.py）则输出 Markdown 文本，并将 Markdown 中内嵌的<img>占位符替换为真实的 MCP 图片内容块（ImageContent）一并返回给大模型，detailed模式还会附加页数信息。

运行时参数会经过validate_params严格校验（inference/base.py），任何不在白名单内的参数名都会抛出ValueError，并列出合法参数集合。各任务合法的动态参数见各自的 params 文件：OCR（9 项，默认关闭文档方向分类与矫正）、PP-StructureV3（31 项）、PaddleOCR-VL（22 项，额外包含temperature、top_p、max_new_tokens、min_pixels/max_pixels、prompt_label等 VLM 采样与图像分辨率参数）。

6. 参数参考

你可以通过环境变量或 CLI 参数控制 MCP Server，两者语义一一对应：

表中默认值与main.py 的 argparse 定义、selection.py 的DEFAULT_MODEL完全一致。另外需要注意：--host与--port仅在--http模式下生效，否则启动时会报错退出（见main.py）。

7. 已知限制

• 本地推理模式下，暴露的 MCP 工具无法处理 Base64 编码的 PDF 文档输入；
• 本地推理模式下，MCP 工具不会根据模型的file_type提示推断文件类型，部分复杂 URL 可能处理失败；
• 对于 PP-StructureV3 和 PaddleOCR-VL 系列，若输入文件中包含图片，返回结果可能显著增加 token 消耗；如果不需要图片内容，可通过提示词显式排除以降低资源消耗。

8. 架构速览：一次工具调用的完整链路

结合源码可以梳理出一次 MCP 工具调用的完整链路（以本地 OCR 为例）：

1. 入口：paddleocr_mcp解析参数 →resolve_model校验模型 →create_inference按“模型 × 来源”组合创建推理实例（inference/factory.py）；
2. 注册：create_task依据_MODEL_TOOLS映射选出工具类，通过Task.register_tools注册到 FastMCP（tasks/base.py）；
3. 输入适配：InputAdapter.normalize/validate/prepare将input_data归一化为后端原生输入（本地 OCR 中 Base64 图片解码为 BGR ndarray，见 inference/ocr/local.py）；
4. 参数合并与校验：get_final_params用用户参数覆盖默认值，validate_params拒绝未知参数（inference/base.py）；
5. 推理：本地模式通过LocalSyncRunner在线程池中执行 PaddleOCR 同步预测（PaddleOCR.predict），避免阻塞事件循环；
6. 结果格式化：_format_result按output_mode输出纯文本摘要或 JSON（OCR）／Markdown+图片内容块（文档解析）。

这一“模型-工具-来源”三层解耦的设计，使得新增模型或推理来源时只需在 selection.py、factory.py 与 tasks/factory.py 中登记即可，无需改动工具调用协议。

9. 快速决策建议

• 只想快速体验：选官方 API（aistudio），只需配置 Access Token，无需本地 GPU 与飞桨环境；
• 离线或数据敏感：选本地推理（local/local-cpu），注意 PaddleOCR-VL 系列不建议 CPU 推理，并按第 3.3.1 节的性能建议裁剪流水线；
• 已有千帆账号且任务为版面解析/文档理解：选千帆 API（qianfan），注意其仅支持PP-StructureV3与PaddleOCR-VL；
• 已有自部署 serving 服务或需要定制服务配置：选自托管 API（self_hosted），Base URL 不要带路径后缀；
• 多客户端远程部署：CLI 加--http --host <ip> --port <port>启动 Streamable HTTP 传输，并视需要开启--verbose调试。

如需继续深入，可阅读仓库内 mcp_server/README_en.md（英文入口）、PaddleOCR 安装指南、PaddleOCR 与 PaddleX 的关系说明 以及 PaddleOCR serving 部署文档。

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR