# 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](/abs/path/C:/Users/anura/OneDrive/Desktop/Comp-PDF-MCP/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:

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

2. Install the package:

```powershell
pip install -U pip
pip install .
```

3. Install the correct PaddlePaddle runtime for your host:

- CPU host:

```powershell
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

```powershell
$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:

```powershell
.\start_server.ps1
```

The server will listen on:

```text
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:

```json
{
  "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](/abs/path/C:/Users/anura/OneDrive/Desktop/Comp-PDF-MCP/clients/client/mcp.json).

## Example tool calls

Base64 image:

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

You can also test from a terminal client:

```powershell
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:

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

Remote PDF by URL:

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

Server-local file:

```json
{
  "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.