opensource/PaddleOCR
3
0
Fork 0
mirror of https://github.com/PaddlePaddle/PaddleOCR.git synced 2026-09-01 15:32:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

[Feat][MCP] Support PaddleOCR-VL-1.5 (#17717)

Browse Source 
* Fix MCP docs

* Support PaddleOCR-VL-1.5

* Accommodate fastmcp 3.0
This commit is contained in:
Lin Manhui
2026-02-26 15:25:36 +08:00
committed by GitHub
parent 0e19cbb3ca
commit 5b15abbe06
5 changed files with 43 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/version3.x/deployment/mcp_server.en.md
+9 -8
View File
@@ -15,9 +15,10 @@ This project provides a lightweight [Model Context Protocol (MCP)](https://model
- **OCR**: Performs text detection and recognition on images and PDF files.
- **PP-StructureV3**: Identifies and extracts text blocks, titles, paragraphs, images, tables, and other layout elements from images or PDF files, converting the input into Markdown documents.
- **PaddleOCR-VL**: Identifies and extracts text blocks, titles, paragraphs, images, tables, and other layout elements from images or PDF files, converting the input into Markdown documents. A VLM-based approach is used.
- **PaddleOCR-VL-1.5**: An upgraded version of PaddleOCR-VL. Compared with PaddleOCR-VL, PaddleOCR-VL-1.5 achieves improvements in both speed and accuracy.
- **Supported Working Modes**
- **Local Python Library**: Runs PaddleOCR pipelines directly on the local machine. This mode requires a suitable local environment and hardware, and is ideal for offline use or privacy-sensitive scenarios.
- **PaddleOCR Official Website Service**: Invokes services provided by the [PaddleOCR Official Website](https://aistudio.baidu.com/paddleocr?lang=en). This is suitable for quick testing, prototyping, or no-code scenarios.
- **PaddleOCR Official Service**: Invokes services provided by the [PaddleOCR Official Website](https://aistudio.baidu.com/paddleocr?lang=en). This is suitable for quick testing, prototyping, or no-code scenarios.
- **Qianfan Platform Service**: Calls the cloud services provided by Baidu AI Cloud's Qianfan large model platform.
- **Self-hosted Service**: Invokes the user's self-hosted PaddleOCR services. This mode offers the advantages of serving and high flexibility. It is suitable for scenarios requiring customized service configurations, as well as those with strict data privacy requirements. **Currently, only the basic serving solution is supported.**
@@ -199,7 +200,7 @@ This section explains how to use the PaddleOCR MCP server within Claude for Desk
pipeline.export_paddlex_config_to_yaml("PP-StructureV3.yaml")
```
**For PaddleOCR-VL, it is note recommended to use CPUs for inference.**
**For PaddleOCR-VL series, it is note recommended to use CPUs for inference.**
**Important**:
@@ -225,7 +226,7 @@ You can configure the MCP server according to your requirements to run in differ
See [2.1 Quick Start](#21-quick-start).
#### Mode 2: PaddleOCR Official Website Service
#### Mode 2: PaddleOCR Official Service
1. Install `paddleocr-mcp`.
2. Obtain the service base URL and AI Studio Community access token.
@@ -292,7 +293,7 @@ Configuration example:
**Note**:
- `PADDLEOCR_MCP_PIPELINE` should be set to the pipeline name. See Section 4 for more details. The Qianfan platform service currently only supports PaddleOCR-VL and PP-StructureV3.
- `PADDLEOCR_MCP_PIPELINE` should be set to the pipeline name. See Section 4 for more details. The Qianfan platform service currently only supports PP-StructureV3 and PaddleOCR-VL.
#### Mode 4: Self-hosted Service
@@ -391,7 +392,7 @@ paddleocr_mcp --help
Example commands:
```bash
# OCR + PaddleOCR official website service + stdio
# OCR + PaddleOCR official service + stdio
PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN=xxxxxx paddleocr_mcp --pipeline OCR --ppocr_source aistudio --server_url https://xxxxxx.aistudio-hub.baidu.com
# PP-StructureV3 + local Python library + stdio
@@ -409,8 +410,8 @@ You can control the MCP server via environment variables or CLI arguments.
| Environment Variable | CLI Argument | Type | Description | Options | Default |
| ------------------------------------- | ------------------------- | ------ | --------------------------------------------------------------------- | ---------------------------------------- | ------------- |
| `PADDLEOCR_MCP_PIPELINE` | `--pipeline` | `str` | Pipeline to run. | `"OCR"`, `"PP-StructureV3"`, `"PaddleOCR-VL"` | `"OCR"` |
| `PADDLEOCR_MCP_PPOCR_SOURCE` | `--ppocr_source` | `str` | Source of PaddleOCR capabilities. | `"local"` (local Python library), `"aistudio"` (PaddleOCR official website service), `"qianfan"` (Qianfan platform service), `"self_hosted"` (self-hosted service) | `"local"` |
| `PADDLEOCR_MCP_PIPELINE` | `--pipeline` | `str` | Pipeline to run. | `"OCR"`, `"PP-StructureV3"`, `"PaddleOCR-VL"`, `"PaddleOCR-VL-1.5"` | `"OCR"` |
| `PADDLEOCR_MCP_PPOCR_SOURCE` | `--ppocr_source` | `str` | Source of PaddleOCR capabilities. | `"local"` (local Python library), `"aistudio"` (PaddleOCR official service), `"qianfan"` (Qianfan platform service), `"self_hosted"` (self-hosted service) | `"local"` |
| `PADDLEOCR_MCP_SERVER_URL` | `--server_url` | `str` | Base URL for the underlying service (required for `aistudio`, `qianfan`, or `self_hosted` modes). | - | `None` |
| `PADDLEOCR_MCP_AISTUDIO_ACCESS_TOKEN` | `--aistudio_access_token` | `str` | AI Studio access token (required for `aistudio` mode). | - | `None` |
| `PADDLEOCR_MCP_TIMEOUT` | `--timeout` | `int` | Read timeout for the underlying requests (seconds). | - | `60` |
@@ -425,4 +426,4 @@ You can control the MCP server via environment variables or CLI arguments.
- In the local Python library mode, the current tools cannot process PDF document inputs that are Base64 encoded.
- In the local Python library mode, the current tools do not infer the file type based on the model's `file_type` prompt, and may fail to process some complex URLs.
- For the PP-StructureV3 and PaddleOCR-VL pipelines, if the input file contains images, the returned results may significantly increase token usage. If image content is not needed, you can explicitly exclude it through prompts to reduce resource consumption.
- For the PP-StructureV3 and PaddleOCR-VL series, if the input file contains images, the returned results may significantly increase token usage. If image content is not needed, you can explicitly exclude it through prompts to reduce resource consumption.
docs/version3.x/deployment/mcp_server.md
+10 -9
View File
@@ -15,9 +15,10 @@ comments: true
- **OCR**：对图像和 PDF 文件进行文本检测与识别。
- **PP-StructureV3**：从图像或 PDF 文件中识别和提取文本块、标题、段落、图片、表格以及其他版面元素，将输入转换为 Markdown 文档。
- **PaddleOCR-VL**：使用基于多模态大模型的方案，从图像或 PDF 文件中识别和提取文本块、标题、段落、图片、表格以及其他版面元素，将输入转换为 Markdown 文档。
- **PaddleOCR-VL-1.5**：PaddleOCR-VL 的升级版，相较于 PaddleOCR-VL，PaddleOCR-VL-1.5 在速度与准确率上均有提升。
- **支持运行在如下工作模式**
- **本地 Python 库**：在本机直接运行 PaddleOCR 产线。此模式对本地环境与计算机性能有一定要求，适用于需要离线使用、对数据隐私有严格要求的场景。
- **PaddleOCR 官网服务**：调用 [PaddleOCR 官网](https://aistudio.baidu.com/paddleocr) 提供的云服务。此模式适合快速体验功能、快速验证方案等，也适用于零代码开发场景。
- **PaddleOCR 官方服务**：调用 [PaddleOCR 官网](https://aistudio.baidu.com/paddleocr) 提供的云服务。此模式适合快速体验功能、快速验证方案等，也适用于零代码开发场景。
- **千帆平台服务**：调用百度智能云千帆大模型平台提供的云服务。
- **自托管服务**：调用用户自托管的 PaddleOCR 服务。此模式具备服务化部署优势及高度灵活性，适用于需要自定义服务配置的场景，同时也适用于对数据隐私有严格要求的场景。**目前暂时只支持基础服务化部署方案。**
@@ -126,7 +127,7 @@ paddleocr_mcp --help
### 2.1 快速开始
接下来以 **PaddleOCR 官网服务** 工作模式为例，引导您快速上手。
接下来以 **PaddleOCR 官方服务** 工作模式为例，引导您快速上手。
1. **安装 `paddleocr-mcp`**
@@ -249,9 +250,9 @@ paddleocr_mcp --help
pipeline.export_paddlex_config_to_yaml("PP-StructureV3.yaml")
```
**对于 PaddleOCR-VL产线，不建议使用 CPU 推理。**
**对于 PaddleOCR-VL 系列，不建议使用 CPU 推理。**
#### 模式二：PaddleOCR 官网服务
#### 模式二：PaddleOCR 官方服务
请参考 [2.1 快速开始](#21-快速开始)。
@@ -285,7 +286,7 @@ paddleocr_mcp --help
**说明**：
- `PADDLEOCR_MCP_PIPELINE` 需要被设置为产线名称。详见第 4 节。千帆平台服务目前仅支持 PaddleOCR-VL 和 PP-StructureV3。
- `PADDLEOCR_MCP_PIPELINE` 需要被设置为产线名称。详见第 4 节。千帆平台服务目前仅支持 PP-StructureV3 和 PaddleOCR-VL。
#### 模式四：自托管服务
@@ -384,7 +385,7 @@ paddleocr_mcp --help
示例命令如下：
```bash
# OCR + PaddleOCR 官网服务 + stdio
# 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
@@ -402,8 +403,8 @@ paddleocr_mcp --pipeline OCR --ppocr_source self_hosted --server_url http://127.
| 环境变量 | 命令行参数 | 类型 | 描述 | 可选值 | 默认值 |
|:---------|:-----------|:-----|:-----|:-------|:-------|
| `PADDLEOCR_MCP_PIPELINE` | `--pipeline` | `str` | 要运行的产线。 | `"OCR"`，`"PP-StructureV3"`，`"PaddleOCR-VL"` | `"OCR"` |
| `PADDLEOCR_MCP_PPOCR_SOURCE` | `--ppocr_source` | `str` | PaddleOCR 能力来源。 | `"local"`（本地 Python 库），`"aistudio"`（PaddleOCR 官网服务），`"qianfan"`（千帆平台服务），`"self_hosted"`（自托管服务） | `"local"` |
| `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` |
@@ -418,4 +419,4 @@ paddleocr_mcp --pipeline OCR --ppocr_source self_hosted --server_url http://127.
- 在本地 Python 库模式下，当前提供的工具无法处理 Base64 编码的 PDF 文档输入。
- 在本地 Python 库模式下，当前提供的工具不会根据模型提示的 `file_type` 推断文件类型，对于一些复杂 URL 可能处理失败。
- 对于 PP-StructureV3 和 PaddleOCR-VL 产线，若输入文件中包含图像，返回结果可能会显著增加 token 使用量。若无需图像内容，可通过提示词明确排除，以降低资源消耗。
- 对于 PP-StructureV3 和 PaddleOCR-VL 系列，若输入文件中包含图像，返回结果可能会显著增加 token 使用量。若无需图像内容，可通过提示词明确排除，以降低资源消耗。
mcp_server/paddleocr_mcp/__main__.py
+6 -4
View File
@@ -32,7 +32,7 @@ def _parse_args() -> argparse.Namespace:
parser.add_argument(
"--pipeline",
choices=["OCR", "PP-StructureV3", "PaddleOCR-VL"],
choices=["OCR", "PP-StructureV3", "PaddleOCR-VL", "PaddleOCR-VL-1.5"],
default=os.getenv("PADDLEOCR_MCP_PIPELINE", "OCR"),
help="Pipeline name.",
)
@@ -137,7 +137,7 @@ def _validate_args(args: argparse.Namespace) -> None:
file=sys.stderr,
)
sys.exit(2)
if args.pipeline not in ("PaddleOCR-VL", "PP-StructureV3"):
if args.pipeline not in ("PP-StructureV3", "PaddleOCR-VL"):
print(
f"{repr(args.pipeline)} is currently not supported when using the {repr(args.ppocr_source)} source.",
file=sys.stderr,
@@ -176,20 +176,22 @@ async def async_main() -> None:
server_name = f"PaddleOCR {args.pipeline} MCP server"
mcp = FastMCP(
name=server_name,
log_level="INFO" if args.verbose else "WARNING",
mask_error_details=True,
)
pipeline_handler.register_tools(mcp)
log_level = "INFO" if args.verbose else "WARNING"
if args.http:
await mcp.run_async(
transport="streamable-http",
host=args.host,
port=args.port,
log_level=log_level,
)
else:
await mcp.run_async()
await mcp.run_async(log_level=log_level)
except Exception as e:
print(f"Failed to start the server: {e}", file=sys.stderr)
mcp_server/paddleocr_mcp/pipelines.py
+14 -1
View File
@@ -918,7 +918,14 @@ class PaddleOCRVLHandler(_LayoutParsingHandler):
)
def _create_local_engine(self) -> Any:
if self._pipeline == "PaddleOCR-VL":
pipeline_version = "v1"
elif self._pipeline == "PaddleOCR-VL-1.5":
pipeline_version = "v1.5"
else:
raise RuntimeError(f"Unknown pipeline {repr(self._pipeline)}")
return PaddleOCRVL(
pipeline_version=pipeline_version,
paddlex_config=self._pipeline_config,
device=self._device,
)
@@ -926,7 +933,12 @@ class PaddleOCRVLHandler(_LayoutParsingHandler):
def _transform_service_kwargs(self, kwargs: Dict[str, Any]) -> Dict[str, Any]:
kwargs = super()._transform_service_kwargs(kwargs)
if self._ppocr_source == "qianfan":
kwargs["model"] = "paddleocr-vl-0.9b"
if self._pipeline == "PaddleOCR-VL":
kwargs["model"] = "paddleocr-vl-0.9b"
else:
raise RuntimeError(
f"Unknown or unsupported pipeline {repr(self._pipeline)}"
)
return kwargs
@@ -934,6 +946,7 @@ _PIPELINE_HANDLERS: Dict[str, Type[PipelineHandler]] = {
"OCR": OCRHandler,
"PP-StructureV3": PPStructureV3Handler,
"PaddleOCR-VL": PaddleOCRVLHandler,
"PaddleOCR-VL-1.5": PaddleOCRVLHandler,
}
mcp_server/pyproject.toml
+4 -5
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "paddleocr_mcp"
version = "0.4.1"
version = "0.5.0"
requires-python = ">=3.10"
dependencies = [
"mcp>=1.5.0",
@@ -14,16 +14,15 @@ dependencies = [
"pillow>=9.0.0",
"puremagic>=1.30.0",
"typing-extensions>=4.0.0",
]
[project.optional-dependencies]
local = [
"paddleocr[doc-parser]>=3.2",
"paddleocr[doc-parser]>=3.4",
]
local-cpu = [
"paddleocr[doc-parser]>=3.2",
"paddlepaddle>=3.0.0",
"paddleocr[doc-parser]>=3.4",
"paddlepaddle>=3.2.1",
]
[project.scripts]