mcp_ocr

Modular OCR MCP server with pluggable backends: Apple Vision, PaddleOCR, and PaddleOCR-VL.

Requires pi-mcp-bridge to connect to pi.

Installation

pip install git+https://github.com/timaliev/mcp_ocr.git#egg=mcp-ocr[vision,paddleocr-vl]

Or via uv:

uv tool install git+https://github.com/timaliev/mcp_ocr.git

Optional dependency groups

Related MCP server: paddleocr-mcp

Configuration

With pi-mcp-bridge

In ~/.pi/agent/settings.json:

{
  "mcpBridge": {
    "servers": [
      {
        "name": "ocr",
        "command": "mcp-ocr",
        "args": []
      }
    ]
  }
}

Standalone MCP client

In ~/.mcp.json:

{
  "mcpServers": {
    "ocr": {
      "command": "mcp-ocr",
      "args": []
    }
  }
}

Backends

Quick comparison

Recommendation: Use Vision for everyday OCR. It's instant, accurate for European languages, and has zero dependencies on macOS. Use PaddleOCR-VL only for CJK text where Vision falls short. Avoid Paddle (Python) backend — it loads 2.5 GB of C++ libraries for comparable results.

Vision (ocr_text_vision, ocr_layout_vision, ocr_table_vision)

• macOS 10.15+, zero install

• GPU/ANE accelerated

• Best for: CJK + major European languages, fast extraction

Paddle (ocr_text_paddle, ocr_layout_paddle, ocr_table_paddle)

• Cross-platform CPU

• Mature PaddleOCR models

• Best for: wide language coverage, when not on macOS

PaddleOCR-VL (ocr_text_paddleocr_vl, ocr_layout_paddleocr_vl, ocr_table_paddleocr_vl)

• macOS 14+, Apple Silicon (M1/M2/M3/M4)

• 0.9B vision-language model, 109 languages (Cyrillic quality is poor)

• Default mode is base (fast, ~2–7s). dynamic mode is 20× slower and produces garbled output

• Formula and chart tasks disabled — the CLI hangs on these (upstream bug)

• Model downloads 1.8 GB on first run; subsequent runs use cache

• Best for: CJK text, when Vision is not available

Development

Environment Variables

Development

git clone https://github.com/timaliev/mcp_ocr.git
cd mcp_ocr
pip install -e .[all]
pytest