Ocr

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

Installation

# Recommended (macOS Apple Silicon):
pip install git+https://github.com/timaliev/pi-mcp_ocr.git#egg=pi-mcp-ocr[vision,paddleocr-vl]

# Cross-platform:
pip install git+https://github.com/timaliev/pi-mcp_ocr.git#egg=pi-mcp-ocr[paddle]

Optional dependency groups

Group	Backend	Requirements
vision	Apple Vision	macOS 10.15+
paddle	PaddleOCR	Cross-platform, CPU
paddleocr-vl	PaddleOCR-VL	macOS 14+, Apple Silicon, paddleocr-vl CLI
all	Everything	All of the above

Configuration

Add to your MCP client config (e.g., mcp.json for pi):

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

Backends

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_table_paddleocr_vl, ocr_formula_paddleocr_vl, ocr_chart_paddleocr_vl)

• macOS 14+, Apple Silicon (M1/M2/M3/M4)
• 0.9B vision-language model, 109 languages
• Best for: highest accuracy, formulas, charts, tables
• Requires: paddleocr-vl CLI from https://github.com/mlx-community/paddleocr-vl.swift

Environment Variables

Variable	Default	Description
PADDLEOCR_VL_BIN	paddleocr-vl	Path to paddleocr-vl CLI binary
PADDLEOCR_VL_TIMEOUT	120	Timeout in seconds for PaddleOCR-VL

Development

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