🔍 PaddleOCR-json MCP

Local OCR for MCP clients, powered by PaddleOCR-json v1.4.1

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

✨ 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.

Related MCP server: Vision-OCR-MCP

🧰 MCP tools

recognize_image and recognize_image_base64 accept include_details=true to include bounding boxes in the normalized result.

🏗️ How it works

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

git clone https://github.com/luffy666code/PaddleOCR-json-MCP.git
cd PaddleOCR-json-MCP
python -m venv .venv

Activate the virtual environment, then install:

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

engine/
├── PaddleOCR-json.exe
└── models/

Linux

engine/
├── bin/
│   └── PaddleOCR-json
├── lib/
└── models/

See engine/README.md for the expected layout.

3. Run the MCP server

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:

{
  "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

{
  "image_path": "C:\\images\\receipt.png",
  "include_details": false
}

Base64 image

{
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "include_details": true
}

A successful normalized result has the shape:

{
  "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

scripts\build_windows.bat

Output:

dist/paddleocr-mcp.exe

Linux

./scripts/build_linux.sh

After building, keep the executable next to the engine/ directory:

runtime/
├── paddleocr-mcp.exe   # Windows example
└── engine/
    ├── PaddleOCR-json.exe
    └── models/

📁 Repository layout

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

• PaddlePaddle/PaddleOCR

• 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 and NOTICE.

If this wrapper is useful, consider starring the upstream OCR projects too. ⭐