OCR.space MCP Server

Python MCP server for OCR.space - extract text from images and PDFs using OCR.

Features

• Six comprehensive tools:
• ocr_file - Extract text from local images/PDFs
• ocr_url - Extract text from images/PDFs at URLs
• ocr_auto - Smart OCR that auto-handles oversized files
• split_pdf - Split large PDFs into API-compatible chunks
• list_languages - Show supported OCR languages
• check_tier_status - Verify API configuration

• Automatic oversized file handling:
• PDFs too large? Automatically split by pages, OCR each chunk, join results
• Images too large? Automatically compress while preserving quality

• Dual-tier support:
• Free tier: 1 MB limit, US servers
• PRO tier: 5 MB limit, EU endpoint for GDPR compliance

• Full API parameter support:
• 26+ languages including auto-detection
• Two OCR engines (optimized for different use cases)
• Table optimization mode
• Auto-rotation detection
• Searchable PDF generation
• Save results as TXT or JSON

Installation

# With uv (recommended)
uv sync

# With pip
pip install -e .

Configuration

API Keys

Get your free API key at ocr.space/ocrapi/freekey.

For PRO features (larger files, EU endpoint), sign up at ocr.space/ocrapi.

Environment Variables

Copy .envrc.example to .envrc and configure:

# Required: Free tier API key
export OCR_SPACE_API_KEY="your-free-api-key"

# Optional: PRO tier for GDPR-compliant EU processing
export OCR_SPACE_PRO_API_KEY="your-pro-api-key"
export OCR_SPACE_PRO_ENDPOINT="https://eu.api.ocr.space/parse/image"

Then enable with direnv allow.

Claude Code / MCP Config

Add to .mcp.json:

{
  "mcpServers": {
    "ocr-space": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/ocr-space-mcp", "ocr-space-mcp"],
      "env": {
        "OCR_SPACE_API_KEY": "${OCR_SPACE_API_KEY}",
        "OCR_SPACE_PRO_API_KEY": "${OCR_SPACE_PRO_API_KEY}",
        "OCR_SPACE_PRO_ENDPOINT": "${OCR_SPACE_PRO_ENDPOINT}"
      }
    }
  }
}

OpenCode Config

Add to opencode.json:

{
  "mcp": {
    "ocr-space": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/ocr-space-mcp", "ocr-space-mcp"],
      "env": {
        "OCR_SPACE_API_KEY": "${OCR_SPACE_API_KEY}",
        "OCR_SPACE_PRO_API_KEY": "${OCR_SPACE_PRO_API_KEY}",
        "OCR_SPACE_PRO_ENDPOINT": "${OCR_SPACE_PRO_ENDPOINT}"
      }
    }
  }
}

Usage

Check Configuration

Check my OCR.space tier status

OCR a Local File

Extract text from /path/to/document.pdf

OCR this image using the PRO tier: /path/to/scan.png

Parameters:

OCR from URL

Extract text from https://example.com/document.png

Smart OCR for Large Files (ocr_auto)

The ocr_auto tool automatically handles files that exceed the API size limits:

OCR this large document: /path/to/big-scan.pdf

How it works:

• PDFs: Splits into chunks by page, OCRs each chunk, joins results
• Images: Compresses (quality + resize) until under limit, then OCRs

Parameters: Same as ocr_file, but no size limit errors!

Split PDF Only

If you just want to split a large PDF without OCR:

Split /path/to/large.pdf for free tier processing

Creates multiple smaller PDF files in a temp directory (or specify output_dir).

List Languages

What OCR languages are supported?

Supported languages: Arabic, Bulgarian, Chinese (Simplified/Traditional), Croatian, Czech, Danish, Dutch, English, Finnish, French, German, Greek, Hungarian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Slovenian, Spanish, Swedish, Thai, Turkish, Ukrainian, Vietnamese.

Use language=auto with Engine 2 for automatic language detection.

Tier Comparison

OCR Engines

Development

# Install with dev dependencies
uv sync --extra dev

# Run linter
uv run ruff check .

# Format code
uv run ruff format .

# Run tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=ocr_space_mcp --cov-report=term-missing

License

MIT - see LICENSE

Links

• OCR.space API Documentation
• Get Free API Key
• GitLab Repository
• GitHub Mirror