Skip to main content
Glama
Sign In
ocr-mcp

ocr-mcp

by asharca
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

OcrPlane CLI

Agent-friendly command line client for the OcrPlane/MineRU OCR API.

ocrplane-cli is the installable package and Docker image name. The installed command is ocrplane.

Features

  • Typer command line interface

  • Pydantic v2 input and output models

  • Rich human-readable terminal output

  • Stable --json output for agents

  • --dry-run request planning

  • Async submit plus polling and paginated result reads

Related MCP server: MCP Document Parse Tool

Requirements

  • Python 3.11+

  • An OcrPlane API base URL

  • An API key from OcrPlane

Online Install

Recommended install with uv:

uv tool install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

Run once without installing:

uvx --from "git+https://github.com/asharca/ocrplane-cli.git" ocrplane --help

Upgrade later:

uv tool upgrade ocrplane-cli

Alternative isolated install with pipx:

pipx install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

If the repository is private or you prefer SSH:

pipx install "git+ssh://git@github.com/asharca/ocrplane-cli.git"
ocrplane --help

Upgrade later:

pipx upgrade ocrplane-cli

Install into the current Python environment with pip:

python3 -m pip install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

Run directly with Docker:

docker run --rm \
  -e OCRPLANE_BASE_URL="https://ocr.rhzy.ai" \
  -e OCRPLANE_API_KEY="mk_xxxxxxxxxxxxxxxxxxxx" \
  -v "$PWD:/workspace" \
  ghcr.io/asharca/ocrplane-cli:latest \
  parse /workspace/report.pdf --json

macOS Install

Using the system Python or Homebrew Python:

cd ~/Code/ocrplane-cli
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
ocrplane --help

If python3 is missing:

brew install python

Install with uv:

brew install uv
uv tool install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

Or install uv with the official standalone installer:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

Optional isolated install with pipx:

brew install pipx
pipx ensurepath
pipx install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

Linux Install

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip git
cd ~/code/ocrplane-cli
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
ocrplane --help

RHEL/CentOS/Fedora:

sudo dnf install -y python3 python3-pip git
cd ~/code/ocrplane-cli
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
ocrplane --help

Optional isolated install with pipx:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

Install with uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "git+https://github.com/asharca/ocrplane-cli.git"
ocrplane --help

Run once with uvx:

uvx --from "git+https://github.com/asharca/ocrplane-cli.git" ocrplane --help

Configure

Set the API endpoint and key:

export OCRPLANE_BASE_URL="https://ocr.rhzy.ai"
export OCRPLANE_API_KEY="mk_xxxxxxxxxxxxxxxxxxxx"

Compatibility aliases are also supported:

MINERU_API_BASE_URL
MINERU_BASE_URL
MINERU_API_KEY
API_KEY
APIKEY

Prefer OCRPLANE_BASE_URL and OCRPLANE_API_KEY for new setups.

To keep local secrets out of git:

cp .env.example .env

Then edit .env and load it before using the CLI:

set -a
source .env
set +a

Quick Start

Validate a request without sending it:

ocrplane parse /workspace/report.pdf --json --dry-run

Submit a document and wait for completion:

ocrplane parse /workspace/report.pdf --json

For large documents, submit first and read results by page:

ocrplane parse /workspace/large.pdf --json --no-wait
ocrplane status <task_id> --json
ocrplane markdown <task_id> --json --offset 0 --max-length 12000
ocrplane blocks <task_id> --json --offset 0 --limit 50

Write result artifacts to disk:

ocrplane parse /workspace/report.pdf --save-dir /workspace/ocr-report

This writes:

  • summary.json

  • result.md

  • content_blocks.json

  • pages.json

Commands

ocrplane parse FILE
ocrplane status TASK_ID
ocrplane markdown TASK_ID
ocrplane blocks TASK_ID
ocrplane result TASK_ID
ocrplane list
ocrplane reprocess TASK_ID
ocrplane settings

Common parse options:

ocrplane parse /workspace/a.pdf \
  --backend pipeline \
  --lang ch \
  --parse-method auto \
  --formula \
  --table \
  --start-page 0 \
  --end-page 9 \
  --timeout 900 \
  --poll-interval 3 \
  --json

Docker

Build locally:

docker build -t ocrplane-cli .

Run against a mounted workspace:

docker run --rm \
  -e OCRPLANE_BASE_URL \
  -e OCRPLANE_API_KEY \
  -v "$PWD:/workspace" \
  ocrplane-cli parse /workspace/report.pdf --json

Published images use:

ghcr.io/asharca/ocrplane-cli:latest

The GitHub Actions workflow publishes this image on pushes to main.

Agent Notes

  • Use --json for machine-readable output.

  • Use --dry-run when planning a call or checking paths.

  • Use --no-wait for large files, then poll with status.

  • Read large markdown with markdown --offset --max-length.

  • Read structured OCR blocks with blocks --offset --limit.

  • Avoid printing API keys in logs or prompts.

Development

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m compileall src/ocrplane
python -m pip wheel . --no-deps -w /tmp/ocrplane-cli-wheel

Available Tools

7 tools
get_content_blocksC

Return paginated structured content blocks, optionally filtered by page_idx.

Inputs: task_id (required), limit, offset, page_idx. Returns: object

get_full_resultA

Return task metadata plus capped markdown and content blocks for small documents.

Inputs: task_id (required), max_blocks, max_markdown_length. Returns: object

get_markdownC

Return a slice of a task's markdown result.

Inputs: task_id (required), offset, max_length. Returns: object

get_task_statusC

Return the current OcrPlane task record for a task id.

Inputs: task_id (required). Returns: object

list_tasksC

List OcrPlane tasks for the configured API key user.

Inputs: page, limit, search, source. Returns: object

parse_documentA

Submit a document to OcrPlane OCR and optionally wait for completion.

Provide exactly one document input: file_path, file_url, or base64_content. For large files, prefer file_url. The tool returns a compact summary; use get_markdown or get_content_blocks to page through large results.

Inputs: lang, wait, backend, file_url, +10 more. Returns: object

reprocess_taskC

Reprocess an existing task, optionally rotating or re-OCRing selected pages.

Inputs: task_id (required), lang, rotate, backend, +6 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    The tools are well-differentiated: parse_document submits, get_task_status checks status, list_tasks lists, and the three getter tools retrieve different result formats (markdown, content blocks, full result) with clear boundaries.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (e.g., get_markdown, list_tasks, parse_document). Only reprocess_task slightly deviates as a compound verb but still fits the pattern.

    Tool Count5/5

    With 7 tools, the server covers the essential OCR workflow (submit, status, retrieve results, list, reprocess) without unnecessary redundancy, making the count appropriate for its purpose.

    Completeness4/5

    The tool set covers the core lifecycle: submission, status polling, result retrieval in multiple formats, listing, and reprocessing. Minor gaps like deletion or batch operations exist but are non-essential for typical OCR tasks.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers