PaddleOCR MCP Server 实战指南把 OCR 与文档解析能力接入 Claude、VSCode 等大模型应用【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCRPaddleOCR MCP Server 是 PaddleOCR 提供的一款轻量级 Model Context Protocol (MCP) 目录下的官方文档与源码实现完整讲解安装配置、四种推理方式本地推理 / 官方 API / 千帆 API / 自托管 API的接入步骤、CLI 运行方式、全部参数参考以及已知限制读完即可将图片与 PDF 转化为结构化数据并驱动 AI 应用。核心能力一览当前支持的模型与 MCP 工具MCP 服务会根据PADDLEOCR_MCP_MODEL选择的模型自动挂载对应的工具tool模型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 文档从源码结构看模型名到工具的映射定义在 selection.pyPP-OCRv5/PP-OCRv6系列映射到ocr工具PP-StructureV3映射到pp_structurev3PaddleOCR-VL全系列映射到paddleocr_vl对应的任务实现分别位于 tasks/ocr.py 与 tasks/doc_parsing.py。默认模型为PP-OCRv6见 selection.py。支持的推理方式本地推理local直接在本地机器上运行 PaddleOCR pipeline对本地环境和硬件性能有一定要求适合离线使用与数据隐私要求严格的场景。官方 APIaistudio调用 PaddleOCR 官方 API适合快速体验功能、验证方案等无代码开发场景。千帆 APIqianfan调用百度智能云千帆平台提供的 API。自托管 APIself_hosted调用用户自行部署的 PaddleOCR 推理服务具备服务化优势与较高的灵活性适合需要定制服务配置以及数据隐私要求严格的场景。当前仅支持基础 serving 方案。四种 provider 在 providers.py 中以枚举形式定义local/aistudio/qianfan/self_hosted其中qianfan与self_hosted走 HTTP 传输aistudio走官方 API 传输local走本地进程传输。使用示例以下是 PaddleOCR MCP Server 与其他工具组合构建的创意用例Demo 1图像笔记写入 Notion在 Claude for Desktop 中从图片中提取手写内容并保存到笔记软件 Notion。PaddleOCR MCP Server 在保留文档结构的同时从图片中提取文字、公式等信息。说明该 Demo 除 PaddleOCR MCP Server 外还使用了 Notion MCP server。Demo 2手写代码一键转可运行脚本在 VSCode 中将手写想法或伪代码一键转换为符合项目编码规范的可运行 Python 脚本并上传至 GitHub 仓库。PaddleOCR MCP Server 先从图片中提取明确手写的代码供后续处理。说明该 Demo 除 PaddleOCR MCP Server 外还使用了 filesystem MCP server。Demo 3复杂文档转为本地可编辑文件在 Claude for Desktop 中将包含复杂表格、公式、手写文字等内容的 PDF 文档或图片转换为本地可编辑文件。Demo 3.1将包含表格与水印的复杂 PDF 文档转换为可编辑的 doc/Word 格式。Demo 3.2将包含公式与表格的图片转换为可编辑的 csv/Excel 格式。1. 安装paddleocr-mcp要求Python 3.10 及以上见 pyproject.toml。paddleocr-mcp默认依赖paddleocr3.7.0因此官方 API、千帆 API、自托管 API 三种模式无需单独安装 PaddleOCR。本地推理则额外需要文档解析依赖以及本地运行 PaddleOCR pipeline 所需的推理引擎详见下文 方法 1本地推理。从 PyPI 安装pip install -U paddleocr-mcp从源码安装git clone https://github.com/PaddlePaddle/PaddleOCR.git pip install -e mcp_server本地推理请按 方法 1本地推理 所述安装对应的可选依赖extras。此外PaddleOCR 还支持通过uvx免安装运行服务详见 2.4 使用uvx。安装完成后可通过以下命令验证paddleocr_mcp --help若命令输出了帮助信息则说明安装成功。该命令的实际实现位于main.py入口脚本paddleocr_mcp在 pyproject.toml 中注册为paddleocr_mcp.__main__:main。2. 与 Claude for Desktop 配合使用本节说明如何在 Claude for Desktop 中使用 PaddleOCR MCP Server步骤稍作调整后同样适用于其他 MCP 宿主。2.1 快速开始以下快速开始以官方 API推理为例安装paddleocr-mcp参考 1. 安装。获取 Access Token从 AI Studio 的 Access Token 页面获取你的访问令牌。添加 MCP 服务器配置找到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打开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 宿主重启 Claude for Desktop 后paddleocr服务器即可在应用中使用。2.2 MCP 宿主配置细节在 Claude for Desktop 的配置文件中需要定义 MCP 服务器的启动方式关键字段如下commandpaddleocr_mcp若可执行文件可在PATH中找到或绝对路径。args可配置的命令行参数例如[--verbose]详见 4. 参数参考。env可配置的环境变量详见 4. 参数参考。2.3 推理方法你可以根据自己的需求配置 MCP 服务器以使用不同的推理方法不同方法的操作流程各不相同下面分别说明。方法 1本地推理 {#方法-1本地推理}安装paddleocr-mcp及本地推理依赖。paddleocr-mcp已依赖 PaddleOCR本地推理额外需要文档解析依赖和一个推理引擎。你可以参考 PaddleOCR 安装指南 手动安装也可以使用对应的可选依赖paddleocr-mcp[local]包含paddleocr[doc-parser]3.7.0不含推理引擎。paddleocr-mcp[local-cpu]在local基础上额外包含 CPU 版 PaddlePaddle 推理引擎paddlepaddle3.2.1。# 安装本地推理所需的文档解析依赖不含推理引擎 pip install paddleocr-mcp[local] # 在 local 基础上额外安装 CPU 版 PaddlePaddle 框架 pip install paddleocr-mcp[local-cpu]这些可选依赖在 pyproject.toml 中定义。为避免依赖冲突强烈建议在独立的虚拟环境中安装。按下述配置示例修改claude_desktop_config.json文件。重启 MCP 宿主。配置示例{ mcpServers: { paddleocr: { command: paddleocr_mcp, args: [], env: { PADDLEOCR_MCP_MODEL: PP-OCRv5, PADDLEOCR_MCP_PPOCR_SOURCE: local } } } }注意事项PADDLEOCR_MCP_MODEL应设置为模型名称详见第 4 节。PADDLEOCR_MCP_PIPELINE_CONFIG为可选配置。若不设置则使用默认 pipeline 配置。如需调整配置例如更换模型可参考 PaddleOCR 文档 导出 pipeline 配置文件并将PADDLEOCR_MCP_PIPELINE_CONFIG设置为该文件的绝对路径。推理性能调优建议如果遇到推理时间长或内存不足的情况可考虑调整 pipeline 配置PP-StructureV3 Pipeline关闭不需要的功能例如将use_formula_recognition设为False以关闭公式识别。使用轻量模型例如将 OCR 模型替换为mobile版本或切换到 PP-FormulaNet-S 等轻量公式识别模型。下面示例代码导出一份 PP-StructureV3 pipeline 配置其中关闭了大部分可选功能并将部分关键模型替换为轻量版本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 推理。方法 2官方 API参考 2.1 快速开始。对于文本识别以外的任务请正确设置PADDLEOCR_MCP_MODEL参数细节见第 4 节。方法 3千帆 API安装paddleocr-mcp。参考千帆平台官方文档获取 API Key。按下述配置示例修改claude_desktop_config.json文件。重启 MCP 宿主。配置示例{ 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——这一点在 selection.py 中以QIANFAN_SUPPORTED_MODELS常量硬编码若在qianfan模式下选择其他模型resolve_model会直接抛出ValueError。PADDLEOCR_MCP_QIANFAN_BASE_URL为千帆 API 的 base URL可选默认值为https://qianfan.baidubce.com/v2/ocr。PADDLEOCR_MCP_QIANFAN_API_KEY为千帆 API 鉴权密钥。方法 4自托管 API在需要运行 PaddleOCR 推理服务器的环境中参考 PaddleOCR serving 文档 运行推理服务器。在需要运行 MCP 服务器的环境中安装paddleocr-mcp。按下述配置示例修改claude_desktop_config.json文件。重启 MCP 宿主。配置示例{ 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应设置为模型名称详见第 4 节。将your-server-url替换为底层服务的 base URL例如http://127.0.0.1:8080不要带/ocr、/layout-parsing之类的路径后缀MCP 会根据 pipeline 自动拼接。2.4 使用uvxPaddleOCR 还支持通过uvx启动 MCP 服务器无需手动安装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 } } } }本地推理依赖、性能调优与 pipeline 配置参考 方法 1本地推理。由于启动方式不同配置文件中的command与args设置与前述方式有所差异但 MCP 服务支持的命令行参数与环境变量如PADDLEOCR_MCP_SELF_HOSTED_BASE_URL仍可用同样的方式设置。3. 运行服务器除 Claude for Desktop 等 MCP 宿主外你也可以通过 CLI 直接运行 PaddleOCR MCP 服务器。运行以下命令打印帮助信息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 --http从源码看CLI 的启动流程位于main.py先解析参数并校验如aistudio必须提供 token、qianfan必须提供 API Key、self_hosted必须提供 base URL随后解析模型名、创建对应的推理后端、注册工具到 FastMCP 服务默认走 stdio 传输加--http则切换为 Streamable HTTP 传输绑定127.0.0.1:8000可通过--host/--port修改。PaddleOCR MCP 服务器支持的全部参数见 4. 参数参考。4. 参数参考你可以通过环境变量或 CLI 参数控制 MCP 服务器环境变量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 base URLaistudio来源可选。-NonePADDLEOCR_MCP_QIANFAN_BASE_URL--qianfan-base-urlstr千帆 API base URLqianfan来源可选。-https://qianfan.baidubce.com/v2/ocrPADDLEOCR_MCP_SELF_HOSTED_BASE_URL--self-hosted-base-urlstr自托管 PaddleX serve base 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 单次请求 HTTP 超时时间秒用于任务提交、状态查询等。-120PADDLEOCR_MCP_AISTUDIO_POLL_TIMEOUT--aistudio-poll-timeoutintAI Studio 任务轮询总超时时间秒。-600PADDLEOCR_MCP_DEVICE--devicestr推理设备仅对local来源生效。-NonePADDLEOCR_MCP_PIPELINE_CONFIG--pipeline_configstrPaddleOCR pipeline 配置文件路径仅对local来源生效。-None---httpbool使用 Streamable HTTP 传输代替 stdio用于远程部署与多客户端。-False---hoststrStreamable HTTP 模式的绑定地址。-127.0.0.1---portintStreamable HTTP 模式的端口。-8000---verbosebool开启详细日志便于调试。-False源码补充说明上表中的参数解析逻辑可在main.py 中逐一对应--http与--host/--port存在联动校验——非 HTTP 模式下指定 host/port 会报错退出见main.py。此外ocr工具还支持通过runtime_params透传管道级运行参数例如use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation、text_det_limit_side_len、text_det_thresh、text_det_box_thresh、text_det_unclip_ratio、text_rec_score_thresh等定义见 inference/ocr/params.py非法参数会被validate_params拒绝见 inference/base.py。5. 已知限制本地推理模式下暴露的 MCP 工具无法处理 Base64 编码的 PDF 文档输入。本地推理模式下暴露的 MCP 工具不会从模型的file_type提示中推断文件类型某些复杂 URL 可能处理失败。对于 PP-StructureV3 与 PaddleOCR-VL 系列若输入文件包含图片返回结果可能显著增加 token 消耗如果不需要图片内容可通过提示词显式排除以降低资源消耗。深入理解工具调用与结果返回机制作为补充这里结合源码梳理一下 MCP 工具的底层执行链路便于你在自定义宿主中调试或扩展模型解析与校验resolve_model校验模型名是否在SUPPORTED_MODELS中并对qianfan来源做额外约束selection.py。推理后端选择create_inference依据 provider 创建对应后端本地/官方/千帆/自托管见 inference/factory.py 与 providers.py。工具注册与调用Task.register_tools将_invoke_tool注册为 FastMCP 工具tasks/base.py。每次调用会依次执行输入归一化、参数校验、调用predict、按output_mode格式化结果tasks/base.py。结果格式化ocr工具在detailed模式下返回 JSON含置信度、文本行数等简单模式下返回纯文本并附带置信度tasks/ocr.py文档解析工具则将 Markdown 中的img标签替换为 MCPImageContenttasks/doc_parsing.py图片统一转为 base64 mimeType 格式tasks/mcp_image.py。总结PaddleOCR MCP Server 将 PaddleOCR 的 OCR、版面解析与 VLM 解析能力以标准 MCP 工具形式开放给大模型应用支持本地推理、官方 API、千帆 API 与自托管 API 四种来源可覆盖从离线隐私场景到云端快速体验的完整需求。通过claude_desktop_config.json中简单的commandenv配置即可完成接入也可用uvx免安装启动配合--http参数还能以 Streamable HTTP 方式做远程部署。本文涉及的仓库源码均可进一步阅读 mcp_server 目录含 README_en.md安装环境细节可参考 安装指南serving 部署可参考 serving 文档。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考