PaddleOCR-MCP

PaddleOCR MCP (Model Context Protocol) server and CLI tool that extracts text from images and outputs results in markdown format. Optimized for fast inference with GPU auto-detection.

MCP Server Configuration

The MCP (Model Context Protocol) server allows integration with MCP clients like Cursor, Claude Desktop, etc.

Use uvx directly (no installation required, automatically downloads from PyPI):

{
  "mcpServers": {
    "fast-paddleocr-mcp": {
      "command": "uvx",
      "args": ["fast-paddleocr-mcp"]
    }
  }
}

MCP Tool: ocr_image

The server provides a single tool called ocr_image that:

• Input: image_path (string) - Path to the input image file
• Output: Returns the path to the generated markdown file containing OCR results
• Automatic optimizations: All performance optimizations are applied automatically with intelligent fallback
• Default language: Uses 'ch' (Chinese and English) by default for maximum compatibility

Example: When called with image_path: "photo.png", it returns "photo.png.md" containing the recognized text.

Note: The server automatically applies all optimizations (HPI, GPU acceleration, image preprocessing, etc.) and falls back to simpler configurations if needed. No configuration required from the caller.

See MCP_README.md for detailed MCP server documentation.

Usage

Basic Usage

The tool is optimized for speed by default with the following settings:

• Fast mode enabled (disables preprocessing for maximum speed)
• PP-OCRv4 (faster mobile models)
• 640px image size limit (faster processing)
• Auto GPU detection (uses GPU if available, falls back to CPU)

# Output will be saved as <image_name>.png.md
# Uses: fast mode + PP-OCRv4 + 640px + auto GPU detection
uvx --from . paddleocr-md image.png

# Specify custom output path
uvx --from . paddleocr-md image.png -o result.md

# Force CPU mode
uvx --from . paddleocr-md image.png --cpu

# Disable fast mode for better accuracy on rotated text
uvx --from . paddleocr-md image.png --no-fast

# Use PP-OCRv5 for better accuracy (slower)
uvx --from . paddleocr-md image.png --ocr-version PP-OCRv5

Default Optimization Settings

The MCP server is optimized for low latency by default with these settings:

• ✅ Fast mode enabled: Disables textline orientation classification (skips one model)
• ✅ PP-OCRv4: Uses faster mobile models (PP-OCRv4_mobile_det, PP-OCRv4_mobile_rec)
• ✅ High-Performance Inference (HPI): Automatically selects optimal inference backend
  • Can reduce latency by 40-73% (e.g., 73.1% reduction on PP-OCRv5_mobile_rec)
  • Supports Paddle Inference, OpenVINO, ONNX Runtime, TensorRT
• ✅ Multi-threaded CPU: Uses all available CPU cores for parallel processing
• ✅ MKL-DNN enabled: Intel CPU optimization for faster inference
• ✅ Single image batch: rec_batch_num=1 for lowest latency per image
• ✅ Auto GPU detection: Automatically uses GPU if available, falls back to CPU
  • GPU device selection: Uses first available GPU (gpu_id=0)
  • TensorRT support: Automatically enabled via HPI if TensorRT is installed
  • GPU memory: Uses default allocation (can be customized if needed)
• ✅ Automatic image preprocessing: Optimizes images before OCR for better performance
  • Automatic downsampling: Resizes large images to maximum 1920px (maintains aspect ratio)
    • Reduces processing time for large images significantly
    • Uses high-quality LANCZOS resampling to preserve text quality
  • Image sharpening: Enhances text edges for improved OCR accuracy
    • Uses unsharp mask filter (radius=1, percent=150, threshold=3)
    • Additional sharpening enhancement (factor=1.2)
    • Makes text characters more distinct and easier to recognize
  • Format conversion: Automatically converts RGBA, LA, P modes to RGB with white background
  • Temporary file management: Automatically cleans up preprocessed images after OCR
• ✅ Logging disabled: Reduces overhead by disabling verbose logging

GPU Performance:

• When GPU is available, HPI automatically selects TensorRT backend for maximum performance
• TensorRT can provide 2-3x speedup compared to standard GPU inference
• First run with HPI may take longer to build the inference engine, but subsequent runs will be much faster

Requirements:

• PaddleOCR >= 2.7.0 with all latest features supported (HPI, MKL-DNN, etc.)
• No backward compatibility - requires latest PaddleOCR version
• For maximum GPU performance: NVIDIA GPU with CUDA support and TensorRT (optional)
• Sufficient GPU memory (typically 1-2GB for mobile models)

Customization Options

1. --no-fast: Disable fast mode for better accuracy

   • Enables textline orientation classification
   • Better accuracy on rotated text, but slower

2. --cpu: Force CPU mode

   • Overrides auto GPU detection
   • Explicitly use CPU

3. --gpu: Force GPU mode

   • Will fail if GPU not available
   • Use when you want to ensure GPU usage

4. --ocr-version PP-OCRv5: Use better accuracy version

   • PP-OCRv5 has better accuracy but slower than PP-OCRv4 (default)
   • Uses server models

5. --max-size <pixels>: Adjust image processing size

   • Default: 640px
   • Larger values (e.g., 960, 1280) = better accuracy, slower
   • Smaller values (e.g., 480) = faster, may reduce accuracy

6. --hpi: High-Performance Inference

   • Automatically selects best inference backend (Paddle Inference, OpenVINO, ONNX Runtime, TensorRT)
   • Requires HPI dependencies: paddleocr install_hpi_deps cpu/gpu
   • Best performance but requires additional setup

Examples

# Basic usage (uses all optimizations by default: fast + PP-OCRv4 + 640px + auto GPU)
uvx --from . paddleocr-md photo.jpg

# Process with custom output
uvx --from . paddleocr-md document.png -o extracted_text.md

# Better accuracy (slower) - disable fast mode and use PP-OCRv5
uvx --from . paddleocr-md image.png --no-fast --ocr-version PP-OCRv5 --max-size 960

# Force CPU mode
uvx --from . paddleocr-md image.png --cpu

# Use High-Performance Inference (requires HPI dependencies)
uvx --from . paddleocr-md image.png --hpi

Output Format

The tool generates a markdown file containing:

• Source image path
• List of detected text (one per line)

Example output (test_image.png.md):

# OCR Result

**Source Image:** `test_image.png`

---

- HelloPaddleOcR
- 10000C

Testing

Run tests using pytest:

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run tests with coverage
pytest --cov=paddleocr_cli --cov-report=html

# Run specific test file
pytest tests/test_mcp_server.py

# Run specific test class or function
pytest tests/test_mcp_server.py::TestGetOCR
pytest tests/test_mcp_server.py::TestGetOCR::test_get_ocr_default_language

The test suite includes:

• OCR instance initialization and caching
• Tool listing and definition
• OCR tool calls with various parameters
• Language parameter handling
• File validation and error handling
• Markdown output generation
• Edge cases and error scenarios

License

MIT