procleaning-mcp

Python MCP Server for PDF OCR batch processing.

Features

• Batch OCR - Process multiple PDF files and save results as Markdown
• Single File OCR - Process a single PDF file directly

Tool

batch_ocr_pdf

OCR process PDF file(s) using the OCR API. Supports both single file and directory modes.

Parameters:

• input_file: Path to a single PDF file to process (mutually exclusive with input_dir)
• input_dir: Directory containing PDF files to process (mutually exclusive with input_file)
• output_dir: Directory to save Markdown results (auto-created if not provided)
• api_key: OCR API key (optional, reads from OCR_API_KEY env var)
• base_url: OCR API base URL (default: https://agent.imqimacau.com)

Usage Modes:

1. Single File Mode: Provide input_file only

   input_file: /path/to/document.pdf
   

2. Batch Mode: Provide input_dir only

   input_dir: /path/to/pdf_directory
   

Note: input_file and input_dir are mutually exclusive. At least one must be provided.

Returns: JSON with processing results (success/fail counts per file)

---

Deployment (For Other Hermes Agents)

This MCP server can be deployed on any machine running Hermes. Follow the steps below.

Prerequisites

• Python 3.10+
• uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Access to Gitea (or download the source code)
• OCR API Key

Step 1: Clone & Install

git clone https://gitea.imqimacau.com/tony-claw/procleaning-mcp.git
cd procleaning-mcp
uv sync

Step 2: Configure API Key

Set your OCR API key as an environment variable:

# Add to shell profile
echo 'export OCR_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Or set it in ~/.hermes/config.yaml directly.

Step 3: Add to Hermes Config

Edit ~/.hermes/config.yaml and add the mcp_servers section:

mcp_servers:
  procleaning:
    command: "uv"
    args: ["run", "--project", "/home/USER/procleaning-mcp", "python", "-m", "procleaning_mcp.server"]
    timeout: 300

Important: Replace /home/USER/procleaning-mcp with the actual path on your machine.

Step 4: Restart Hermes

Restart your Hermes agent to load the new MCP server. The tool mcp_procleaning_batch_ocr_pdf will be available in conversations.

Step 5: Test

Run a test in Hermes:

input_file: /path/to/test.pdf
output_dir: /path/to/output

---

Local Testing

cd procleaning-mcp
uv run python -m procleaning_mcp.server