OwlOCR MCP

OwlOCR MCP

MCP (Model Context Protocol) server for PDF and image OCR on macOS. Supports two backends:

• OwlOCR CLI - Higher accuracy (recommended)
• Vision Framework - No external dependencies

Features

• 📄 PDF OCR - Extract text from PDF files page by page with separators
• 🖼️ Image OCR - Extract text from PNG, JPEG, and other image formats
• 🌏 Multi-language - Korean + English by default (configurable)
• 🔄 Dual Backend - Auto-selects OwlOCR if available, falls back to Vision Framework
• ⚡ Async - Non-blocking execution for MCP clients

Benchmark Results

Tested on a 4-page Korean theological document with Hebrew text:

Winner: OwlOCR CLI - Faster and more accurate.

Requirements

• macOS (uses Apple Vision Framework / OwlOCR.app)
• Python 3.11+
• OwlOCR.app (optional, for better accuracy)

Installation

Using uv (recommended)

git clone https://github.com/yourusername/owlocr-mcp.git
cd owlocr-mcp
uv sync

Using pip

git clone https://github.com/yourusername/owlocr-mcp.git
cd owlocr-mcp
pip install -e .

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "owlocr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/owlocr-mcp", "owlocr-mcp"]
    }
  }
}

Generic MCP Client

{
  "mcpServers": {
    "owlocr": {
      "command": "/path/to/owlocr-mcp/.venv/bin/python",
      "args": ["-m", "owlocr_mcp.server"]
    }
  }
}

Available Tools

ocr_pdf_to_text

Extract text from a PDF file.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| pdf_path | string | required | Absolute path to the PDF file || pages | list[int] | null | Page numbers to process (1-based). If null, all pages || dpi | int | 200 | Resolution for rendering. Higher = better quality but slower || backend | string | "auto" | "auto", "owlocr", or "vision" || languages | list[string] | null | Language codes (Vision only). Default: ["ko-KR", "en-US"] |

Example:

Extract text from /Users/me/document.pdf using OwlOCR

Output:

첫 번째 페이지 내용...

===== Page 2 =====

두 번째 페이지 내용...

--- OCR Complete: 2 page(s) processed using OwlOCR CLI ---

ocr_image_to_text

Extract text from an image file.

Parameters:| Parameter | Type | Default | Description ||-----------|------|---------|-------------|| image_path | string | required | Absolute path to the image file || backend | string | "auto" | "auto", "owlocr", or "vision" || languages | list[string] | null | Language codes (Vision only) |

check_ocr_backends

Check available OCR backends on the system.

Output:

OCR Backend Status:

✅ Vision Framework: Available (macOS built-in)
✅ OwlOCR CLI: Available (/Applications/OwlOCR.app)

Recommendation: Use backend='owlocr' for best accuracy

Backend Selection

Running the Benchmark

Compare backends on your own PDF:

# Both backends
uv run python benchmark.py /path/to/your.pdf

# With accuracy comparison (requires ground truth)
uv run python benchmark.py /path/to/your.pdf --show-text

# Specific backend only
uv run python benchmark.py /path/to/your.pdf --method owlocr
uv run python benchmark.py /path/to/your.pdf --method vision

Project Structure

owlocr-mcp/
├── src/owlocr_mcp/
│   ├── __init__.py
│   ├── server.py        # MCP server with tools
│   ├── ocr.py           # Vision Framework backend
│   ├── ocr_owlocr.py    # OwlOCR CLI backend
│   └── pdf.py           # PDF processing utilities
├── benchmark.py          # Performance comparison script
├── pyproject.toml
└── README.md

How It Works

OwlOCR Backend

1. Render PDF pages to PNG using pypdfium2
2. Copy images to OwlOCR sandbox: ~/Library/Containers/JonLuca-DeCaro.OwlOCR/Data/tmp/
3. Run CLI: /Applications/OwlOCR.app/Contents/MacOS/OwlOCR --cli --input <file>
4. Combine results with page separators

Vision Framework Backend

1. Render PDF pages to PNG using pypdfium2
2. Load as CIImage via PyObjC
3. Create VNRecognizeTextRequest with accurate recognition level
4. Process with VNImageRequestHandler
5. Sort results by position and combine

Troubleshooting

"OwlOCR.app not found"

Install OwlOCR from owlocr.com or use backend="vision".

File picker dialog appears

This happens when OwlOCR can't access files outside its sandbox. The MCP server handles this by copying files to the sandbox temp directory automatically.

Poor accuracy on specific languages

For Vision Framework, specify languages explicitly:

ocr_pdf_to_text(pdf_path, languages=["ja-JP", "en-US"])

Supported language codes: ko-KR, en-US, ja-JP, zh-Hans, zh-Hant, etc.

License

MIT License - see LICENSE file.

Acknowledgments

• OwlOCR by JonLuca DeCaro
• MCP Python SDK
• Apple Vision Framework