docs/version3.x/deployment/mcp_server.md
PaddleOCR 提供轻量级的 Model Context Protocol（MCP） 服务器，旨在将 PaddleOCR 的文字识别、版面解析等能力集成到各种大模型应用中。
以下展示了使用 PaddleOCR MCP 服务器结合其他工具搭建的创意案例：
在 Claude for Desktop 中，提取图像中的手写内容，并存到笔记软件 Notion。PaddleOCR MCP 服务器从图像中提取了文字、公式等信息，并保留了文档的结构。
<div align="center"> </div>在 VSCode 中，根据手写思路或伪代码一键转换为可运行并符合项目代码风格规范的 Python 脚本，并将其上传到 GitHub 仓库中。PaddleOCR MCP 服务器从图像中准确提取手写代码供后续步骤使用。
<div align="center"> </div>在 Claude for Desktop 中，将含有复杂表格、公式、手写文字等内容的 PDF 文档或图片转存为本地可编辑文件。
含表格水印复杂文档PDF 转为 doc/Word 可编辑格式：
<div align="center"> </div>含公式表格图片转为 csv/Excel 可编辑格式：
<div align="center"> </div>本节将介绍如何通过 pip 安装 paddleocr-mcp 库。
paddleocr-mcp 外，还需要参考 PaddleOCR 安装文档 安装飞桨框架和 PaddleOCR。paddleocr-mcp[local]：包含 PaddleOCR（不包含飞桨框架）。paddleocr-mcp[local-cpu]：在 local 基础上额外包含 CPU 版本的飞桨框架。uvx 等方式免安装运行服务器。详情请参考 2. 在 Claude for Desktop 中使用 中的说明。使用 pip 安装 paddleocr-mcp 库的命令如下：
# 从 PyPI 安装
pip install -U paddleocr-mcp
# 从项目源码安装
git clone https://github.com/PaddlePaddle/PaddleOCR.git
pip install -e mcp_server
# 通过指定 extra 安装可选依赖
# 同时安装 PaddleOCR
pip install "paddleocr-mcp[local]"
# 同时安装 PaddleOCR 和 CPU 版本飞桨框架
pip install "paddleocr-mcp[local-cpu]"
可通过以下命令检查是否安装成功：
paddleocr_mcp --help
如果执行上述命令后打印出了帮助信息，则说明安装成功。
本节将介绍如何在 Claude for Desktop 中使用 PaddleOCR MCP 服务器。对于其他 MCP 主机，也可参照本节的步骤，并根据实际情况进行相应调整。
接下来以 PaddleOCR 官方服务 工作模式为例，引导您快速上手。
安装 paddleocr-mcp
请参考 1. 安装。
获取服务基础 URL 与星河社区访问令牌
在 此页面 点击左上角的“API”，复制“文字识别（PP-OCRv5）”对应的 API_URL 去掉端点末尾（/ocr）的部分，即服务的基础 URL（如 https://xxxxxx.aistudio-app.com），以及 TOKEN，即您的访问令牌。您可能需要注册并登陆飞桨星河社区帐号。
添加 MCP 服务器配置
在以下位置之一找到 Claude for Desktop 配置文件：
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json打开 claude_desktop_config.json 文件，参考如下示例调整配置，填充到 claude_desktop_config.json 中。
{
"mcpServers": {
"paddleocr": {
"command": "paddleocr_mcp",
"args": [],
"env": {
"PADDLEOCR_MCP_PIPELINE": "OCR",
"PADDLEOCR_MCP_PPOCR_SOURCE": "aistudio",
"PADDLEOCR_MCP_SERVER_URL": "<your-server-url>",
"PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN": "<your-access-token>"
}
}
}
}
说明：
<your-server-url> 替换为上一步获取的服务基础 URL。<your-access-token> 替换为您的访问令牌。注意：
paddleocr_mcp 无法在系统 PATH 中找到，请将 command 设置为可执行文件的绝对路径。重启 MCP 主机
重启 Claude for Desktop。新的 paddleocr 服务现在应该可以在应用中使用了。
在 Claude for Desktop 的配置文件中，您需要定义 MCP 服务器的启动方式。关键字段如下：
command：paddleocr_mcp（如果可执行文件可在 PATH 中找到）或绝对路径。args：可配置命令行参数，如 ["--verbose"]。详见 4. 参数说明。env：可配置环境变量。详见 4. 参数说明。您可以根据需求配置 MCP 服务器，使其运行在不同的工作模式。不同工作模式需要的操作流程有所不同，下面将详细介绍。
paddleocr-mcp、飞桨框架和 PaddleOCR。对于飞桨框架和 PaddleOCR，可以参考 PaddleOCR 安装文档 手动安装，也可以通过 paddleocr-mcp[local] 或 paddleocr-mcp[local-cpu] 方式于 paddleocr-mcp 一同安装。为避免依赖冲突，强烈建议在独立的虚拟环境中安装。claude_desktop_config.json 文件内容。配置示例：
{
"mcpServers": {
"paddleocr": {
"command": "paddleocr_mcp",
"args": [],
"env": {
"PADDLEOCR_MCP_PIPELINE": "OCR",
"PADDLEOCR_MCP_PPOCR_SOURCE": "local"
}
}
}
}
说明：
PADDLEOCR_MCP_PIPELINE 需要被设置为产线名称。详见第 4 节。
PADDLEOCR_MCP_PIPELINE_CONFIG 为可选项，不设置时使用产线默认配置。如需调整配置，例如更换模型，请参考 PaddleOCR 文档 导出产线配置文件，并将 PADDLEOCR_MCP_PIPELINE_CONFIG 设置为配置文件的绝对路径。
推理性能提示：
如果使用过程中出现推理耗时过长、内存不足等问题，可考虑参考如下建议调整产线配置：
OCR 产线：建议更换 mobile 系列模型。例如，您可以在产线配置文件中将检测和识别模型分别修改为 PP-OCRv5_mobile_det 和 PP-OCRv5_mobile_rec。
PP-StructureV3 产线：
use_formula_recognition 为 False 以禁用公式识别。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 推理。
请参考 2.1 快速开始。
对于文字识别以外的任务，请在 PaddleOCR 官网获取任务对应的服务基础 URL，并正确设置 PADDLEOCR_MCP_PIPELINE 与 PADDLEOCR_MCP_SERVER_URL（参数说明详见第 4 节）。
paddleocr-mcp。claude_desktop_config.json 文件内容。将 PADDLEOCR_MCP_QIANFAN_API_KEY 设置为千帆平台的 API key。配置示例：
{
"mcpServers": {
"paddleocr": {
"command": "paddleocr_mcp",
"args": [],
"env": {
"PADDLEOCR_MCP_PIPELINE": "PaddleOCR-VL",
"PADDLEOCR_MCP_PPOCR_SOURCE": "qianfan",
"PADDLEOCR_MCP_SERVER_URL": "https://qianfan.baidubce.com/v2/ocr",
"PADDLEOCR_MCP_QIANFAN_API_KEY": "<your-api-key>"
}
}
}
}
说明：
PADDLEOCR_MCP_PIPELINE 需要被设置为产线名称。详见第 4 节。千帆平台服务目前仅支持 PP-StructureV3 和 PaddleOCR-VL。paddleocr-mcp。claude_desktop_config.json 文件内容。将您的服务地址填入 PADDLEOCR_MCP_SERVER_URL (例如："http://127.0.0.1:8000")。配置示例：
{
"mcpServers": {
"paddleocr": {
"command": "paddleocr_mcp",
"args": [],
"env": {
"PADDLEOCR_MCP_PIPELINE": "OCR",
"PADDLEOCR_MCP_PPOCR_SOURCE": "self_hosted",
"PADDLEOCR_MCP_SERVER_URL": "<your-server-url>"
}
}
}
}
说明：
PADDLEOCR_MCP_PIPELINE 需要被设置为产线名称。详见第 4 节。<your-server-url> 替换为底层服务的基础 URL（如：http://127.0.0.1:8000）。uvxPaddleOCR 也支持通过 uvx 启动 MCP 服务器。这种方式不需要手动安装 paddleocr-mcp。主要步骤如下：
claude_desktop_config.json 文件。示例如下：自托管服务模式示例：
{
"mcpServers": {
"paddleocr": {
"command": "uvx",
"args": [
"--from",
"paddleocr-mcp",
"paddleocr_mcp"
],
"env": {
"PADDLEOCR_MCP_PIPELINE": "OCR",
"PADDLEOCR_MCP_PPOCR_SOURCE": "self_hosted",
"PADDLEOCR_MCP_SERVER_URL": "<your-server-url>"
}
}
}
}
本地模式（CPU 推理，使用可选依赖 local-cpu）示例：
{
"mcpServers": {
"paddleocr": {
"command": "uvx",
"args": [
"--from",
"paddleocr_mcp[local-cpu]",
"paddleocr_mcp"
],
"env": {
"PADDLEOCR_MCP_PIPELINE": "OCR",
"PADDLEOCR_MCP_PPOCR_SOURCE": "local"
}
}
}
}
如需了解本地模式的依赖、性能调优及产线配置，请参考 模式一：本地 Python 库 部分。
由于使用了不一样的启动方式，配置文件中 command 和 args 的设置都与前文介绍的方式存在不同，但 MCP 服务本身支持的命令行参数与环境变量（如 PADDLEOCR_MCP_SERVER_URL）仍然可以以相同的方式设置。
除了在 Claude for Desktop 等 MCP 主机中使用外，您也可以通过 CLI 运行 PaddleOCR MCP 服务器。
执行以下命令可以打印帮助信息：
paddleocr_mcp --help
示例命令如下：
# OCR + PaddleOCR 官方服务 + stdio
PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN=xxxxxx paddleocr_mcp --pipeline OCR --ppocr_source aistudio --server_url https://xxxxxx.aistudio-hub.baidu.com
# PP-StructureV3 + 本地 Python 库 + stdio
paddleocr_mcp --pipeline PP-StructureV3 --ppocr_source local
# OCR + 本地服务 + Streamable HTTP
paddleocr_mcp --pipeline OCR --ppocr_source self_hosted --server_url http://127.0.0.1:8080 --http
在 4. 参数说明 中可以了解 PaddleOCR MCP 服务器支持的全部参数。
您可以通过环境变量或命令行参数来控制 MCP 服务器的行为。
| 环境变量 | 命令行参数 | 类型 | 描述 | 可选值 | 默认值 |
|---|---|---|---|---|---|
PADDLEOCR_MCP_PIPELINE | --pipeline | str | 要运行的产线。 | "OCR"，"PP-StructureV3"，"PaddleOCR-VL"，"PaddleOCR-VL-1.5" | "OCR" |
PADDLEOCR_MCP_PPOCR_SOURCE | --ppocr_source | str | PaddleOCR 能力来源。 | "local"（本地 Python 库），"aistudio"（PaddleOCR 官方服务），"qianfan"（千帆平台服务），"self_hosted"（自托管服务） | "local" |
PADDLEOCR_MCP_SERVER_URL | --server_url | str | 底层服务基础 URL（aistudio、qianfan、self_hosted 模式下必需）。 | - | None |
PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN | --aistudio_access_token | str | AI Studio 访问令牌（aistudio 模式下必需）。 | - | None |
PADDLEOCR_MCP_TIMEOUT | --timeout | int | 底层服务请求的读取超时时间（秒）。 | - | 60 |
PADDLEOCR_MCP_DEVICE | --device | str | 指定运行推理的设备（仅在 local 模式下生效）。 | - | None |
PADDLEOCR_MCP_PIPELINE_CONFIG | --pipeline_config | str | PaddleOCR 产线配置文件路径（仅在 local 模式下生效）。 | - | None |
| - | --http | bool | 使用 Streamable HTTP 传输而非 stdio（适用于远程部署和多客户端）。 | - | False |
| - | --host | str | Streamable HTTP 模式的主机地址。 | - | "127.0.0.1" |
| - | --port | int | Streamable HTTP 模式的端口。 | - | 8000 |
| - | --verbose | bool | 启用详细日志记录，便于调试。 | - | False |
file_type 推断文件类型，对于一些复杂 URL 可能处理失败。