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 构建的轻量级 MCPModel Context ProtocolServer可将文本识别、版面解析等能力以标准 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完全一致模型MCP 工具名功能说明PP-OCRv5、PP-OCRv5-latin、PP-OCRv6ocr对图片和 PDF 文件执行文本检测与识别PP-StructureV3pp_structurev3从图片或 PDF 中识别并抽取文本块、标题、段落、图片、表格等版面元素将输入转换为 Markdown 文档PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6paddleocr_vl基于 VLM视觉大语言模型的版面解析方案将输入转换为 Markdown 文档在源码层面模型与工具的绑定通过 tasks/factory.py 完成注册ocr对应OCRTaskpp_structurev3对应PPStructureV3Taskpaddleocr_vl对应PaddleOCRVLTask其中后两者继承自DocParsingTask见 tasks/doc_parsing.py共享 Markdown 文档解析输出逻辑。1.2 支持的推理方式MCP Server 支持四种推理来源InferenceProvider枚举定义于 providers.py本地推理local直接在本地机器上运行 PaddleOCR 流水线。对本地环境和硬件性能有一定要求适用于离线使用、数据隐私要求严格的场景。官方 APIaistudio调用 PaddleOCR 官方 APIAI Studio。适合快速体验功能、验证方案等无代码开发场景。千帆 APIqianfan调用百度智能云千帆平台提供的 API。自托管 APIself_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-mcppaddleocr-mcp需要Python 3.10 及以上版本。它默认依赖paddleocr3.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 可以看到其核心依赖包括mcp1.5.0、fastmcp2.0.0、httpx0.24.0、numpy1.24.0、paddleocr3.7.0、pillow9.0.0、puremagic1.30.0等并提供了两个可选依赖组paddleocr-mcp[local]包含paddleocr[doc-parser]3.7.0不含推理引擎paddleocr-mcp[local-cpu]在local基础上额外包含 CPU 版飞桨推理引擎paddlepaddle3.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推理为例安装paddleocr-mcp参考第 2 节。获取 Access Token在 AI Studio 的 Access Token 页面获取你的访问令牌。添加 MCP Server 配置找到claude_desktop_config.json配置文件——macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinux~/.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设置为可执行文件的绝对路径。重启 MCP Host重启 Claude for Desktop 后paddleocrServer 即可在应用中使用。3.2 MCP Host 配置字段详解在 Claude for Desktop 的配置文件中需要定义 MCP Server 的启动方式关键字段如下commandpaddleocr_mcp若可执行文件在PATH中或可执行文件的绝对路径args可配置的命令行参数例如[--verbose]详见第 6 节参数参考env可配置的环境变量详见第 6 节参数参考。3.3 四种推理方式的配置3.3.1 方法一本地推理 {#method-1-local-inference}安装paddleocr-mcp及本地推理依赖。paddleocr-mcp已依赖 PaddleOCR本地推理额外需要文档解析依赖和推理引擎。可参考 PaddleOCR 安装指南 手动安装或使用对应的可选依赖paddleocr-mcp[local]包含paddleocr[doc-parser]3.7.0不含推理引擎paddleocr-mcp[local-cpu]基于local额外包含 CPU 版飞桨推理引擎paddlepaddle3.2.1。# 安装本地推理所需的文档解析依赖不含推理引擎 pip install paddleocr-mcp[local] # 在 local 基础上再安装 CPU 版飞桨框架 pip install paddleocr-mcp[local-cpu]为避免依赖冲突强烈建议在隔离的虚拟环境中安装。参照下面的配置示例修改claude_desktop_config.json。重启 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_classifyFalse, # 关闭文档图像方向分类 use_doc_unwarpingFalse, # 关闭文本图像矫正 use_textline_orientationFalse, # 关闭文本行方向分类 use_formula_recognitionFalse, # 关闭公式识别 use_seal_recognitionFalse, # 关闭印章文本识别 use_table_recognitionFalse, # 关闭表格识别 use_chart_recognitionFalse, # 关闭图表解析 # 使用轻量模型 text_detection_model_namePP-OCRv5_mobile_det, text_recognition_model_namePP-OCRv5_mobile_rec, layout_detection_model_namePP-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安装paddleocr-mcp。参考千帆平台官方文档获取 API Key。参照下面的配置示例修改claude_desktop_config.json。重启 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-VLPADDLEOCR_MCP_QIANFAN_BASE_URL为千帆 API 的基础 URL可选PADDLEOCR_MCP_QIANFAN_API_KEY是你的千帆 API Key用于身份认证。3.3.4 方法四自托管 API在需要运行 PaddleOCR 推理服务器的环境中参考 PaddleOCR serving 部署文档 启动推理服务器在需要运行 MCP Server 的环境中安装paddleocr-mcp参照下面的配置示例修改claude_desktop_config.json重启 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。主要步骤如下安装 uv修改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_TOKENxxxxxx 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 --httpMCP 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按内容自动判别图片或 PDFData URLdata:前缀的 Base64 编码输入。不同来源的适配器行为略有差异本地推理LocalInputAdapter会将 Base64 图片解码为 BGR 的 numpy 数组、将 Base64 PDF 物化为临时文件AI StudioAIStudioInputAdapter会把本地路径或临时文件上传为文件路径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_toolinput_data文件输入格式取决于配置的推理来源output_modesimple输出纯文本detailed输出 JSONfile_typeimage或pdf当 HTTP 类 API 无法从输入推断类型时需要显式指定return_images文档解析输出是否包含图片runtime_params可选流水线参数JSON 对象。以ocr工具为例tasks/ocr.pysimple模式返回识别文本并附带置信度与行数摘要如Confidence: 98.3% | 12 text linesdetailed模式返回包含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 文件OCR9 项默认关闭文档方向分类与矫正、PP-StructureV331 项、PaddleOCR-VL22 项额外包含temperature、top_p、max_new_tokens、min_pixels/max_pixels、prompt_label等 VLM 采样与图像分辨率参数。6. 参数参考你可以通过环境变量或 CLI 参数控制 MCP Server两者语义一一对应环境变量CLI 参数类型说明可选值默认值PADDLEOCR_MCP_MODEL--modelstr运行的模型MCP 会根据模型自动选择工具PP-OCRv5、PP-OCRv5-latin、PP-OCRv6、PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6PP-OCRv6PADDLEOCR_MCP_PPOCR_SOURCE--ppocr_sourcestrPaddleOCR 能力来源local本地推理、aistudio官方 API、qianfan千帆 API、self_hosted自托管 APIlocalPADDLEOCR_MCP_AISTUDIO_BASE_URL--aistudio-base-urlstrAI Studio API 基础 URLaistudio来源可选-NonePADDLEOCR_MCP_QIANFAN_BASE_URL--qianfan-base-urlstr千帆 API 基础 URLqianfan来源可选-https://qianfan.baidubce.com/v2/ocrPADDLEOCR_MCP_SELF_HOSTED_BASE_URL--self-hosted-base-urlstr自托管 PaddleX serve 基础 URLself_hosted来源必填-NonePADDLEOCR_MCP_QIANFAN_API_KEY--qianfan_api_keystr千帆 API 认证密钥qianfan来源必填-NonePADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN--aistudio_access_tokenstrAI Studio 访问令牌aistudio来源必填-NonePADDLEOCR_MCP_HTTP_TIMEOUT--http-timeoutint同步 APIqianfan、self_hosted的 HTTP 读取超时秒-600PADDLEOCR_MCP_AISTUDIO_REQUEST_TIMEOUT--aistudio-request-timeoutintAI Studio API 单次请求超时秒适用于任务提交、状态检查等-120PADDLEOCR_MCP_AISTUDIO_POLL_TIMEOUT--aistudio-poll-timeoutintAI Studio 任务轮询总超时秒-600PADDLEOCR_MCP_DEVICE--devicestr推理设备仅local来源生效-NonePADDLEOCR_MCP_PIPELINE_CONFIG--pipeline_configstrPaddleOCR 流水线配置文件路径仅local来源生效-None---httpbool使用 Streamable HTTP 传输而非 stdio用于远程部署和多客户端-False---hoststrStreamable HTTP 模式绑定的主机地址-127.0.0.1---portintStreamable HTTP 模式绑定的端口-8000---verbosebool开启详细日志以便调试-False表中默认值与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 为例入口paddleocr_mcp解析参数 →resolve_model校验模型 →create_inference按“模型 × 来源”组合创建推理实例inference/factory.py注册create_task依据_MODEL_TOOLS映射选出工具类通过Task.register_tools注册到 FastMCPtasks/base.py输入适配InputAdapter.normalize/validate/prepare将input_data归一化为后端原生输入本地 OCR 中 Base64 图片解码为 BGR ndarray见 inference/ocr/local.py参数合并与校验get_final_params用用户参数覆盖默认值validate_params拒绝未知参数inference/base.py推理本地模式通过LocalSyncRunner在线程池中执行 PaddleOCR 同步预测PaddleOCR.predict避免阻塞事件循环结果格式化_format_result按output_mode输出纯文本摘要或 JSONOCRMarkdown图片内容块文档解析。这一“模型-工具-来源”三层解耦的设计使得新增模型或推理来源时只需在 selection.py、factory.py 与 tasks/factory.py 中登记即可无需改动工具调用协议。9. 快速决策建议只想快速体验选官方 APIaistudio只需配置 Access Token无需本地 GPU 与飞桨环境离线或数据敏感选本地推理local/local-cpu注意 PaddleOCR-VL 系列不建议 CPU 推理并按第 3.3.1 节的性能建议裁剪流水线已有千帆账号且任务为版面解析/文档理解选千帆 APIqianfan注意其仅支持PP-StructureV3与PaddleOCR-VL已有自部署 serving 服务或需要定制服务配置选自托管 APIself_hostedBase 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
