PaddleOCR MCP Server

This project provides a single MCP server that hosts PaddleOCR on one machine in your local network. Other devices can call the OCR tool over MCP without installing PaddleOCR, PaddlePaddle, or OCR models on every system.

For a step-by-step setup walkthrough, see USER_GUIDE.md.

What it does

• Hosts an MCP server on 0.0.0.0 so devices on the same LAN can connect.
• Exposes OCR as MCP tools instead of local dependencies.
• Supports multiple simultaneous users through pooled OCR workers.
• Accepts image or PDF input as:
  • base64 payloads
  • HTTP/HTTPS URLs
  • host-local file paths on the server machine
• Tunes OCR behavior using a content_type preset:
  • document
  • dense_document
  • receipt
  • invoice
  • id_card
  • handwritten
  • table

Recommended Python version

Use Python 3.10, 3.11, or 3.12.

paddleocr and paddlepaddle often lag behind the newest Python releases, so Python 3.14 is not a safe choice for this server.

Install on the host machine

1. Create a virtual environment:

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install the package:

pip install -U pip
pip install .

3. Install the correct PaddlePaddle runtime for your host:

• CPU host:

pip install paddlepaddle

• GPU host: Install the PaddlePaddle build that matches your CUDA version from the official PaddlePaddle instructions, then call the tool with use_gpu=true.

Run the MCP server on your LAN host

$env:MCP_HOST="0.0.0.0"
$env:MCP_PORT="8000"
$env:MCP_TRANSPORT="streamable-http"
$env:OCR_WORKERS="2"
python .\run_server.py

If the console script paddle-ocr-mcp is available in your environment, you can use that too. run_server.py is the most reliable option when the package itself was not installed into the venv.

For Windows, you can also use:

.\start_server.ps1

The server will listen on:

http://YOUR-HOST-IP:8000/mcp

Replace YOUR-HOST-IP with the local IP address of the host machine, such as 192.168.1.25.

Exposed MCP tools

list_ocr_profiles

Returns the supported OCR content presets and when to use them.

extract_text

Main OCR tool with these parameters:

• source: base64 string, URL, or host-local path
• source_type: base64, url, or host_path
• content_type: preset for OCR tuning
• language: PaddleOCR language code such as en
• filename: optional filename hint for base64 uploads
• max_pages: max PDF pages to render
• use_gpu: enable GPU inference on a GPU-ready host
• download_timeout_seconds: URL fetch timeout

Example MCP client configuration

Example for an MCP client that supports streamable HTTP servers:

{
  "mcpServers": {
    "paddle-ocr-lan": {
      "url": "http://192.168.1.25:8000/mcp"
    }
  }
}

A ready-to-copy client config is also included at clients/client/mcp.json.

Example tool calls

Base64 image:

{
  "source": "iVBORw0KGgoAAAANSUhEUgAA...",
  "source_type": "base64",
  "filename": "invoice.png",
  "content_type": "invoice",
  "language": "en"
}

You can also test from a terminal client:

python .\src\paddle_ocr_mcp\client_cli.py --server http://127.0.0.1:8000/mcp --tool list_ocr_profiles
python .\src\paddle_ocr_mcp\client_cli.py --server http://127.0.0.1:8000/mcp --file C:\path\to\scan.pdf --content-type document --max-pages 2

Or with the helper script:

.\test_client.ps1
.\test_client.ps1 -File "C:\path\to\scan.pdf" -ContentType document -MaxPages 2

Remote PDF by URL:

{
  "source": "https://example.local/files/receipt.pdf",
  "source_type": "url",
  "content_type": "receipt",
  "language": "en",
  "max_pages": 2
}

Server-local file:

{
  "source": "C:\\\\shared\\\\scan.jpg",
  "source_type": "host_path",
  "content_type": "id_card",
  "language": "en"
}

Result shape

The OCR tool returns structured output including:

• combined extracted text
• average confidence
• per-page text
• per-line bounding boxes and confidence

Notes for real deployments

• Open the chosen port in the host firewall for your local subnet.
• For remote devices, prefer base64 or url inputs instead of host_path.
• The first request may be slower because PaddleOCR can download model files on first use.
• If you want stricter access control, put this service behind a reverse proxy on your LAN.
• Increase OCR_WORKERS if you need more concurrent OCR throughput and the host has enough RAM.