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

Related MCP server: EasyOCR MCP Server

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