Skip to main content
Glama

OCR.space MCP Server

Pipeline Status Coverage Ruff Python 3.11+ License: MIT

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:

Parameter

Description

Default

file_path

Path to image/PDF (required)

-

tier

free or pro

free

language

OCR language code

eng

ocr_engine

1 (fast) or 2 (accurate)

1

output_path

Save result to file

-

output_format

txt or json

txt

detect_orientation

Auto-rotate image

false

scale

Upscale low-res images

false

is_table

Optimize for tables

false

is_create_searchable_pdf

Generate searchable PDF

false

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

Feature

Free

PRO

File size limit

1 MB

5 MB

Server location

US only

EU available

Rate limit

500/day

Unlimited

GDPR compliance

No

Yes (EU endpoint)

Price

Free

$30/month

OCR Engines

Engine

Best For

Engine 1

Faster processing, Asian languages, large images

Engine 2

Auto-language detection, special characters, rotated text

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

Available Tools

6 tools
check_tier_statusA

Check which API tiers are configured and available. Shows which environment variables are set.

Inputs: no named parameters.

list_languagesA

List all supported OCR languages with their codes.

Inputs: no named parameters.

ocr_autoA

Smart OCR that automatically handles oversized files. For PDFs: splits into chunks, OCRs each, and joins results. For images: compresses to fit within size limit before OCR. Use this when you don't know if the file exceeds the size limit.

Inputs: file_path (required), tier, language, ocr_engine, +2 more.

ocr_fileA

Extract text from a local image or PDF file using OCR.space API. Supports PNG, JPG, GIF, BMP, TIFF, PDF. Free tier: max 1 MB. PRO tier: max 5 MB (EU endpoint for GDPR). Optionally saves result to txt or json file.

Inputs: file_path (required), tier, scale, is_table, +7 more.

ocr_urlA

Extract text from an image or PDF at a URL using OCR.space API. The URL must be publicly accessible. Free tier: max 1 MB. PRO tier: max 5 MB.

Inputs: url (required), tier, scale, is_table, +5 more.

split_pdfA

Split a large PDF into smaller chunks that fit within API size limits. Useful for processing PDFs that exceed the 1 MB (free) or 5 MB (pro) limit. Each chunk contains as many pages as possible while staying under the limit.

Inputs: file_path (required), tier, output_dir.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: URL-based OCR, file-based OCR, auto-handling of oversized files, PDF splitting, language listing, and tier status check. There is no overlap between these operations.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., ocr_url, split_pdf, list_languages). The 'ocr_' prefix for the three OCR variations and clear verbs for helpers make the set easy to predict.

    Tool Count5/5

    With 6 tools, the server is well-scoped: three OCR methods, one PDF utility, and two informational tools. This is neither too sparse nor overloaded for the domain.

    Completeness5/5

    The toolset covers the core OCR lifecycle end-to-end: extracting from URL or file, handling oversized inputs via auto-splitting/compression, splitting PDFs manually, and providing necessary supporting info (languages, tier status). No obvious gaps remain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers