PaddleOCR-json MCP
by luffy666code
README.md
<div align="center">
# 🔍 PaddleOCR-json MCP
**Local OCR for MCP clients, powered by PaddleOCR-json v1.4.1**
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](https://github.com/hiroi-sora/PaddleOCR-json/releases/tag/v1.4.1)
[](LICENSE)
[](https://github.com/luffy666code/PaddleOCR-json-MCP/actions/workflows/ci.yml)
A lightweight **Model Context Protocol (MCP)** wrapper that exposes local
PaddleOCR-json text recognition to any compatible MCP client.
**Image path · Base64 · local processing · reusable engine process**
</div>
---
## ✨ Features
- 🖼️ Recognize text from a local image path.
- 🧩 Recognize Base64 or `data:image/...;base64,...` input.
- 📐 Optionally return text boxes and confidence scores.
- ⚡ Reuse one PaddleOCR-json process across multiple requests.
- 🔁 Restart once automatically when an OCR request fails.
- 🧹 Cleanly terminate the child process when the MCP server exits.
- 🪟 Windows and 🐧 Linux runtime layouts supported by the wrapper.
- 🔒 OCR runs through a local PaddleOCR-json runtime; no remote OCR API is required.
- 🔌 Client-agnostic stdio MCP server — no dependency on a specific agent platform.
## 🧰 MCP tools
| Tool | Purpose |
| --- | --- |
| `recognize_image` | OCR a local image file. |
| `recognize_image_base64` | OCR an image supplied as Base64. |
| `paddleocr_status` | Check engine files and current subprocess status without starting OCR. |
`recognize_image` and `recognize_image_base64` accept `include_details=true` to
include bounding boxes in the normalized result.
## 🏗️ How it works
```text
MCP client
│ JSON-RPC over stdio
▼
FastMCP wrapper (main.py)
│ line-oriented JSON over stdin/stdout
▼
PaddleOCR-json v1.4.1
│
└── models / native runtime files
```
The wrapper keeps the OCR engine alive for reuse. A single stdout reader feeds
responses through a queue, requests are serialized with a lock, and shutdown
uses terminate → wait → kill as a fallback.
## 🚀 Quick start
### 1. Clone and install
```bash
git clone https://github.com/luffy666code/PaddleOCR-json-MCP.git
cd PaddleOCR-json-MCP
python -m venv .venv
```
Activate the virtual environment, then install:
```bash
python -m pip install -U pip
python -m pip install -e .
```
### 2. Add the PaddleOCR-json runtime
Download **PaddleOCR-json v1.4.1** from the upstream release page:
https://github.com/hiroi-sora/PaddleOCR-json/releases/tag/v1.4.1
Place the runtime under `engine/`.
**Windows**
```text
engine/
├── PaddleOCR-json.exe
└── models/
```
**Linux**
```text
engine/
├── bin/
│ └── PaddleOCR-json
├── lib/
└── models/
```
See [`engine/README.md`](engine/README.md) for the expected layout.
### 3. Run the MCP server
```bash
python main.py
```
The server uses **stdio**, so in normal use it is started by your MCP client
rather than run interactively.
## 🔌 MCP client configuration
A generic source-mode configuration looks like this:
```json
{
"mcpServers": {
"paddleocr": {
"command": "python",
"args": ["/absolute/path/to/PaddleOCR-json-MCP/main.py"]
}
}
}
```
If you build a standalone wrapper, point `command` at the generated executable
instead. The exact configuration file location depends on your MCP client.
> The repository intentionally avoids client-specific placeholder syntax and
> deployment metadata. Keep client/platform adapters outside the reusable core.
## 🧪 Tool examples
### Local image
```json
{
"image_path": "C:\\images\\receipt.png",
"include_details": false
}
```
### Base64 image
```json
{
"image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
"include_details": true
}
```
A successful normalized result has the shape:
```json
{
"code": 100,
"text": "Hello OCR",
"count": 1,
"lines": [
{
"text": "Hello OCR",
"score": 0.99,
"box": [[10, 12], [120, 12], [120, 38], [10, 38]]
}
]
}
```
## 📦 Build a standalone wrapper
The engine and model files remain external so they can be updated separately
from the Python wrapper.
**Windows**
```bat
scripts\build_windows.bat
```
Output:
```text
dist/paddleocr-mcp.exe
```
**Linux**
```bash
./scripts/build_linux.sh
```
After building, keep the executable next to the `engine/` directory:
```text
runtime/
├── paddleocr-mcp.exe # Windows example
└── engine/
├── PaddleOCR-json.exe
└── models/
```
## 📁 Repository layout
```text
PaddleOCR-json-MCP/
├── main.py
├── pyproject.toml
├── engine/
│ └── README.md
├── scripts/
│ ├── build_windows.bat
│ └── build_linux.sh
├── .github/
│ ├── workflows/ci.yml
│ └── ISSUE_TEMPLATE/bug_report.yml
├── CONTRIBUTING.md
├── SECURITY.md
├── NOTICE
└── LICENSE
```
Generated `build/`, `dist/`, logs, virtual environments, PaddleOCR-json engine
binaries, and model files are intentionally excluded from Git.
## 🔐 Privacy & security
The wrapper itself talks to a **local PaddleOCR-json process** and does not
require a cloud OCR API. Images provided by file path stay on the MCP host as
far as this wrapper is concerned. Your MCP client or host may implement its own
logging, telemetry, or file handling, so review that environment separately.
Do not expose this MCP server to untrusted callers without considering local
file access: `recognize_image` can read any image path that the server process
has permission to access.
## 🙏 Credits
This repository is an independent community wrapper around:
- [hiroi-sora/PaddleOCR-json](https://github.com/hiroi-sora/PaddleOCR-json)
- [PaddlePaddle/PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
- [FastMCP](https://github.com/jlowin/fastmcp)
PaddleOCR-json v1.4.1 is licensed under the Apache License 2.0. This repository
does not claim to be an official PaddlePaddle or PaddleOCR-json project.
## 📄 License
Apache License 2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
---
<div align="center">
If this wrapper is useful, consider starring the upstream OCR projects too. ⭐
</div>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues