{ "jsonrpc": "2.0", "id": 2, "result": { "content": [{"type": "text", "text": "{\"language\":\"ch\",\"count\":2,\"text\":\"你好世界\nHello OCR\"}"}], "isError": false } } ``` 即 OCR 成功。若 `isError` 为 `true`,看 `content` 里的错误信息(例如跨机访问时本机路径无效,需改用 data URI 或服务端可达的 URL)。 ### 其他:stdio 端到端测试 ```bash python tests/test_mcp_client.py ``` ## 接入 MCP 客户端 ### Codex 编辑 Codex 配置文件(Windows:`~/.codex/config.toml`,即 `%USERPROFILE%\.codex\config.toml`): ```toml [mcp_servers.ocr] enabled = true url = "http://192.168.7.49:8000/mcp" ``` 保存后重启 Codex,即可在对话中让其"识别这张图片里的文字"。 ### Claude Desktop 编辑配置文件(macOS:`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows:`%APPDATA%\Claude\claude_desktop_config.json`): ```json { "mcpServers": { "paddleocr": { "url": "http://192.168.7.49:8000/mcp", "type": "http" } } } ``` ### Cursor 在 Cursor 设置 → MCP 中添加 HTTP 类型的 MCP Server,URL 填 `http://192.168.7.49:8000/mcp`。 ## 提供的 MCP 工具 ### `recognize_text` 对图片、PDF 或办公文档执行 OCR 文本识别。 | 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | `image` | string | 必填 | 本地文件路径、`http(s)` URL、`data:image/...;base64,...` 或裸 base64;支持图片、PDF 与办公文档(doc/ppt/xls 等) | | `language` | string | `"ch"` | 语言代码:`ch` / `en` / `japan` / `korean` | | `detail` | bool | `false` | 坐标框 `box` 始终返回;为 `true` 时额外返回置信度 `confidence` | | `min_confidence` | float | `0.0` | 过滤低于该置信度的行(0-1,0 表示保留全部)| | `model` | string | `"mobile"` | 模型变体:`mobile`(快,适合清晰印刷体)/ `server`(准,适合手写/模糊)| 返回示例: ```json { "language": "ch", "count": 2, "recognized_text": "你好世界\nHello OCR", "lines": [ {"text": "你好世界", "box": [[25, 58], [300, 58], [300, 114], [25, 114]], "page": 0}, {"text": "Hello OCR", "box": [[40, 120], [220, 120], [220, 154], [40, 154]], "page": 0} ] } ``` > 每行 `lines` 始终返回,且自带坐标框 `box` 与 `page` 页码(从 0 开始);`detail=true` 时每行额外带 `confidence`。 > 顶层键为 `recognized_text`(非 `text`,因 Dify 保留 `text` 作为工作流变量名)。 > `box` 是四点角框 `[[x1,y1],[x2,y1],[x2,y2],[x1,y2]]`(顺时针、像素坐标,来自检测多边形); > 与 `recognize_layout` 的 `box`(`[x1,y1,x2,y2]` 四值轴对齐框)格式不同。 > > **多页 PDF**:PDF 按页逐张识别,各行带 `page` 页码(0 起),`box` 坐标基于其所在页; > `recognized_text` 把所有页的文本按顺序换行拼接。 ### `recognize_layout` 对图片、PDF 或办公文档执行**版面分析**(基于 PP-Structure),还原表格/标题/段落等结构。与 `recognize_text`(扁平文本行)不同,它把页面切分为多个版面区块 (`title`/`text`/`table`/`figure`/`formula`/...),识别表格并转为 HTML 与 Markdown (保留行列结构),同时重建阅读顺序,每个区块都带坐标框 `box`。 | 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | `image` | string | 必填 | 本地文件路径、`http(s)` URL、`data:image/...;base64,...` 或裸 base64;支持图片、PDF 与办公文档(doc/ppt/xls 等) | | `language` | string | `"ch"` | 语言代码:`ch` / `en` / `japan` / `korean` | | `output` | string | `"markdown"` | 顶层便捷内容:`markdown`(整页 Markdown,表格保留)或 `text`(仅扁平文本)。结构化数据(`regions`/`tables`)始终返回 | | `flat` | bool | `true` | 输出形态开关,见下方「返回形态」:**Dify 用 `true`(默认)**,把 `regions`/`tables` 序列化为 JSON 字符串;Codex / Claude / 原始 MCP 用 `false` 取回嵌套 dict | | `model` | string | `"mobile"` | 模型变体:`mobile`(快,适合清晰印刷体)/ `server`(准,适合手写/模糊)。控制 PP-StructureV3 内部 OCR 子模型 | 返回字段: 返回形态(`flat` 参数决定): | `flat` | 适用 | 结构化数据键 | 类型 | |-------|------|------------|------| | `true`(默认) | **Dify** | `regions_json` / `tables_json` | JSON 字符串(Dify 工作流变量只接受基本类型,嵌套 dict 会报 `Only basic types and lists are allowed`)| | `false` | Codex / Claude / 原始 MCP | `regions` / `tables` | 嵌套 dict / list | - `regions`:版面区块列表,每项含 `{type, text, box, page}`,表格区块额外含 `{html, markdown}`。 - `tables`:识别到的表格列表,每项含 `{html, markdown, box, cell_count, page}`。 - `markdown`:整页 Markdown 渲染结果,表格以 Markdown 表格语法保留行列结构;多页 PDF 时各页之间以 `---` 分隔。 - `region_count` / `table_count`:区块数与表格数;`width`/`height`:页面像素尺寸。 - `page_count`:页数(单张图片为 `1`,PDF 为实际页数)。返回示例(含一张 2x2 表格的表单): ```json { "language": "ch", "region_count": 2, "table_count": 1, "regions": [ {"type": "title", "text": "员工信息表", "box": [40, 20, 410, 70], "page": 0}, { "type": "table", "box": [30, 90, 430, 260], "text": "...

姓名

年龄

", "html": "

姓名	年龄
张三	30

", "markdown": "| 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 30 |" } ], "tables": [ {"html": "...

", "markdown": "| 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 30 |", "box": [30, 90, 430, 260], "cell_count": 4, "page": 0} ], "markdown": "# 员工信息表\n\n| 姓名 | 年龄 |\n| --- | --- |\n| 张三 | 30 |" } ``` > 上例为单页(图片或单页 PDF),故顶层 `page_count` 省略(为 `1`)。多页 PDF 时 > 每个 region/table 都带其所在页的 `page` 索引(0 起),并额外返回顶层 `page_count`。 > > `box` 为 `[x1, y1, x2, y2]`(左上/右下,像素坐标,基于其所在页)。表格的 `markdown` 由服务端 > 把识别出的 HTML 表格转换而来,`colspan`/`rowspan` 会展开为重复单元格以保持网格。 > **引擎与子 pipeline**:`recognize_layout` 默认启用表格/版面/文字识别。公式/图表/印章 > 识别**仅在原生 paddle 引擎**下可用(即 `OCR_ENGINE` 未强制 onnx、x86_64 环境)——paddlex > 的这三类模型没有 onnx 包,在 `onnxruntime` 引擎下(aarch64 默认 / `OCR_ENGINE=onnxruntime`) > 会被自动关闭(否则加载即报 `does not provide a 'onnx' package`)。设 `OCR_LAYOUT_FULL=1` 强制开启(仅 paddle 引擎有意义)。 ### `list_supported_languages` 返回本服务支持的语言代码与说明,无需参数。 ## 环境变量 | 变量 | 默认值 | 说明 | |------|--------|------| | `MCP_TRANSPORT` | `stdio` | 传输方式:`stdio` 或 `streamable-http` | | `MCP_HOST` | `0.0.0.0` | HTTP 模式监听地址 | | `MCP_PORT` | `8000` | HTTP 模式监听端口 | | `MCP_ALLOWED_HOSTS` | (仅 loopback) | 允许的 Host 头(逗号分隔,跨机访问必填) | | `MCP_ALLOWED_ORIGINS` | (仅 loopback) | 允许的 Origin 头(逗号分隔) | OCR 模型与推理相关: | 变量 | 默认值 | 说明 | |------|--------|------| | `OCR_VERSION` | `PP-OCRv5` | PaddleOCR 模型版本。paddleocr >=3.7 默认 v6 会在 CPU 段错误,故锁回 v5。可选 `PP-OCRv4`/`PP-OCRv6` | | `OCR_PIR` | `0` | 设为 `1` 时不关闭 paddle 的 PIR 执行器(默认关闭以规避 CPU 段错误) | | `OCR_ENGINE` | 自动 | 推理引擎。aarch64(树莓派等)自动用 `onnxruntime` 规避 native 段错误;x86 用 `paddle`。可强制 `onnxruntime`/`paddle` | | `OCR_DEVICE` | `cpu` | 推理设备:`cpu` / `gpu` / `gpu:0`。用 `gpu` 需 GPU 版 paddlepaddle + NVIDIA 驱动 | | `OCR_MAX_IMAGE_SIDE` | `2880` | OCR 前将图片长边缩放到此值以下(像素)。调小可显著加速,但过小会丢失小字 | Docker 镜像默认设置 `MCP_TRANSPORT=streamable-http`。 ## 本地 stdio 模式适用于 Claude Desktop、Cursor 等通过子进程接入的客户端。 ```bash # 不设置 MCP_TRANSPORT 即为 stdio python -m ocr_mcp ``` Claude Desktop 配置(stdio): ```json { "mcpServers": { "paddleocr": { "command": "python", "args": ["-m", "ocr_mcp"], "cwd": "C:/develop/pythonws/ocr-server", "env": { "MCP_TRANSPORT": "stdio" } } } }

PaddleOCR MCP Server

Installation