PaddleOCR-MCP

# 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):** ```json { "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](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) ```bash # 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 ```bash # 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`): ```markdown # OCR Result **Source Image:** `test_image.png` --- - HelloPaddleOcR - 10000C ``` ## Testing Run tests using pytest: ```bash # 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