PaddleOCR MCP Server

📖 中文  |  🌐 English

🏮 中文

PaddleOCR MCP Server

基于 PaddleOCR 的 模型上下文协议 (MCP) 服务器，为 AI Agent 提供本地图片文字识别能力。

🚀 核心优势

💡 搭配 DeepSeek-v4 的低成本方案：PaddleOCR 负责提取图片文字，DeepSeek-v4 等大模型负责理解分析——本地运行，无需 GPU，开发成本趋近于零。

Related MCP server: mcp-vision

🤖 自动识别机制

即使你的模型不支持看图（纯文本模型），AI Agent 也能自动调用 ocr_image MCP 工具识别图片文字后返回结果。

举个例子：

1. 用户发送一张截图

2. AI Agent 发现该模型不支持直接看图

3. 自动调用 ocr_image 工具提取图片中的文字

4. 基于提取的文字内容进行分析和回答

这意味着：

• ✅ 无需切换模型 — 纯文本模型也能"看懂"图片

• ✅ 零额外配置 — MCP 挂载后自动生效

• ✅ 透明使用 — 用户只需发图，Agent 自动处理

✨ 功能特性

• 纯文字识别 — ocr_image(image_path) 一键提取图片中全部文字

• 中英混合 — 原生支持中文 + 英文混合识别

• 109 种语言 — 覆盖全球主要语言

• 本地离线 — 无需 API Key，首次下载模型后完全离线

• 轻量快速 — PP-OCRv6 模型仅 34.5M 参数，CPU 流畅运行

• MCP 标准 — 兼容所有 MCP 客户端

🎯 适用场景

• 🤖 搭配 DeepSeek-v4、GLM、Qwen 等大模型做图片内容理解

• 📄 文档扫描件、截图文字提取

• 🏭 工业场景：车牌、标签、单据识别

• 🌐 多语言文档处理

📦 快速开始

环境要求

• Python 3.8~3.12

• Node.js 18+（仅 Claude Code 等客户端需要，服务端本身不需要）

安装

# 安装 PaddleOCR 和 PaddlePaddle
pip install paddlepaddle==3.2.0 paddleocr

# 克隆本仓库
git clone https://github.com/YuanJinke/paddleocr_mcp.git
cd paddleocr_mcp

⚠️ Windows 用户注意：PaddlePaddle 3.3.1 有 oneDNN 兼容性问题，请务必安装 3.2.0 版本。

配置到你的 MCP 客户端

claude mcp add -s user paddleocr -- python /路径/paddleocr_mcp.py

或添加到 ~/.claude.json：

{
  "mcpServers": {
    "paddleocr": {
      "type": "stdio",
      "command": "python",
      "args": ["/路径/paddleocr_mcp.py"]
    }
  }
}

添加到 ~/.hermes/config.yaml：

mcp_servers:
  paddleocr:
    command: python
    args: ["/路径/paddleocr_mcp.py"]
    timeout: 120
    connect_timeout: 120

然后重启 Hermes。

{
  "mcpServers": {
    "paddleocr": {
      "type": "stdio",
      "command": "python",
      "args": ["/路径/paddleocr_mcp.py"]
    }
  }
}

使用示例

向你的 AI Agent 发送：

调用 ocr_image 识别 /图片路径/screenshot.png，然后告诉我图片里写了什么。

返回结果示例：

{"text": "Hello World\n你好世界", "lines": ["Hello World", "你好世界"]}

🔧 本地测试

# 启动服务
python paddleocr_mcp.py

# 另开终端发送测试请求
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ocr_image","arguments":{"image_path":"/路径/test.png"}},"id":1}' | python paddleocr_mcp.py

⚠️ 已知问题

• 客户端聊天框无法上传图片：大部分 AI IDE（如 Trae、Cursor 等）的聊天输入框只在模型支持视觉时才允许上传图片。如果你使用的是纯文本模型（如 DeepSeek-v4、GPT-4o-mini 等），聊天框不会显示图片上传按钮。

  • ✅ 解决方案：通过命令行或 API 调用时传入图片路径即可，MCP 工具不受聊天 UI 限制。例如在 Trae 的 .opencode.json 配置好 MCP 后，Agent 仍可通过上下文中的图片路径调用 OCR。

• Windows + oneDNN：PaddlePaddle 3.3.1 有 oneDNN 属性转换 bug。使用 3.2.0 或设置 FLAGS_use_onednn=0

• 首次运行：自动下载模型权重（约 50 MB），后续使用缓存

📄 许可证

MIT — 随意使用，随意修改。

🌐 English

PaddleOCR MCP Server

A Model Context Protocol (MCP) server providing local OCR capabilities via PaddleOCR. Works with any MCP-compatible AI agent.

🚀 Key Advantages

💡 Low-cost solution with DeepSeek-v4: PaddleOCR extracts text from images, then pairs with any LLM (DeepSeek-v4, GPT, Claude, GLM, etc.) for understanding — all running locally, zero GPU required, near-zero development cost.

🤖 Auto-OCR Mechanism

Even if your model doesn't support images (text-only model), the AI Agent will automatically call the ocr_image MCP tool to read the image and return the text content.

How it works:

1. User sends a screenshot

2. AI Agent detects the model can't process images natively

3. Auto-calls ocr_image to extract text from the image

4. Analyzes and responds based on the extracted text

This means:

• ✅ No model switching required — text-only models can "see" images

• ✅ Zero extra config — works automatically once MCP is mounted

• ✅ Transparent usage — just send the image, the agent handles the rest

✨ Features

• Pure OCR — ocr_image(image_path) extracts all text from images

• Chinese + English — mixed-language recognition out of the box

• 109 languages — global language coverage

• Local & offline — no API keys, no network calls after initial model download

• Lightweight — PP-OCRv6 (34.5M params) runs on CPU

• MCP standard — compatible with all MCP clients

🎯 Use Cases

• 🤖 DeepSeek-v4, GLM, Qwen image understanding pipeline

• 📄 Document scanning & screenshot OCR

• 🏭 Industrial: license plates, labels, receipts

• 🌐 Multilingual document processing

📦 Quick Start

Prerequisites

• Python 3.8–3.12

• Node.js 18+ (for client-side tools only, not needed by the server itself)

Install

# Install PaddleOCR and PaddlePaddle
pip install paddlepaddle==3.2.0 paddleocr

# Clone this repo
git clone https://github.com/YuanJinke/paddleocr_mcp.git
cd paddleocr_mcp

⚠️ Windows users: PaddlePaddle 3.3.1 has a known oneDNN bug. Pin to 3.2.0 as shown above.

Configure in your MCP client

claude mcp add -s user paddleocr -- python /path/to/paddleocr_mcp.py

Or add to ~/.claude.json:

{
  "mcpServers": {
    "paddleocr": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/paddleocr_mcp.py"]
    }
  }
}

Add to ~/.hermes/config.yaml:

mcp_servers:
  paddleocr:
    command: python
    args: ["/path/to/paddleocr_mcp.py"]
    timeout: 120
    connect_timeout: 120

Then restart Hermes.

{
  "mcpServers": {
    "paddleocr": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/paddleocr_mcp.py"]
    }
  }
}

Usage Example

Send to your AI agent:

Call ocr_image on `/path/to/screenshot.png" and tell me what it says.

Example result:

{"text": "Hello World\n你好世界", "lines": ["Hello World", "你好世界"]}

🔧 Local Test

# Start server
python paddleocr_mcp.py

# Send test request
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ocr_image","arguments":{"image_path":"/path/to/test.png"}},"id":1}' | python paddleocr_mcp.py

⚠️ Known Issues

• Chat UI cannot upload images: Most AI IDEs (Trae, Cursor, etc.) only show the image upload button when the model supports vision natively. If you're using a text-only model (e.g., DeepSeek-v4, GPT-4o-mini), the chat input won't have an image attachment option.

  • ✅ Workaround: The MCP tool works regardless of UI limitations. Pass the image file path via CLI or API calls, and the agent can still use ocr_image to extract text. For Trae, once MCP is configured in .opencode.json, the agent can OCR images referenced by path in the context.

• Windows + oneDNN: PaddlePaddle 3.3.1 has a oneDNN attribute conversion bug. Use 3.2.0 or set FLAGS_use_onednn=0.

• First run: Model weights (~50 MB) auto-downloaded on first use. Subsequent runs use cache.

📄 License

MIT — free to use, modify, and distribute.