# PaddleOCR MCP Server

Small deployment wrapper for running `paddleocr_mcp` as a long-lived service on a VPS.

Default setup binds to `127.0.0.1:8000` so the service is not exposed to the public internet. Use SSH tunnel first; Cloudflare Tunnel can be added later.

## Requirements

- Linux VPS with `systemd`
- Python 3.10+
- `git`

## Install

```bash
sudo git clone <repo-url> /apps/paddleocr-mcp-server
cd /apps/paddleocr-mcp-server
sudo cp .env.example .env
sudo bash scripts/install.sh
sudo systemctl enable --now paddleocr-mcp
```

Check status:

```bash
./scripts/status.sh
```

Follow logs:

```bash
./scripts/logs.sh
```

## Local Access From Laptop

Use SSH tunnel:

```bash
ssh -L 8000:127.0.0.1:8000 user@your-vps
```

Then configure OpenCode with:

```json
{
  "mcp": {
    "paddleocr": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp",
      "enabled": true,
      "timeout": 120000
    }
  }
}
```

## Configuration

Edit `.env`:

```bash
PADDLEOCR_MCP_MODEL=PP-OCRv5
PADDLEOCR_MCP_PPOCR_SOURCE=local
PADDLEOCR_MCP_HOST=127.0.0.1
PADDLEOCR_MCP_PORT=8000
```

Useful models:

- `PP-OCRv5`: default text OCR, good starting point.
- `PP-OCRv6`: newer text OCR.
- `PP-StructureV3`: document layout parsing to Markdown, heavier on CPU.

Restart after config changes:

```bash
sudo systemctl restart paddleocr-mcp
```

## Upgrade

```bash
cd /apps/paddleocr-mcp-server
sudo git pull
sudo .venv/bin/pip install -r requirements.txt
sudo systemctl restart paddleocr-mcp
```

## Security

Default host is `127.0.0.1`. Do not bind to `0.0.0.0` unless you put auth and HTTPS in front of it.

Cloudflare Tunnel + Access can be added later without changing the service.