Skip to main content
Glama

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
offsetNo
task_idYes
page_idxNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It only states basic behavior without disclosing pagination details, empty results, or permissions required. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise, but omits critical parameter and usage info. Front-loaded with action but too brief for a 4-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description is incomplete for the complexity. With 4 parameters and no annotations, it should explain pagination and parameter roles. Output schema exists but parameter semantics are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description only mentions 'page_idx' filter. It does not explain 'limit', 'offset', or 'task_id'. Fails to add meaning beyond parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns paginated structured content blocks with optional filtering. It is distinct from sibling tools like get_full_result or get_markdown, though 'content blocks' could be more specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like get_full_result or list_tasks. The description does not mention context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_full_resultA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes
max_blocksNo
max_markdown_lengthNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description bears the burden of behavioral disclosure. It mentions capping behavior (max_blocks, max_markdown_length) and the limitation to 'small documents', but does not detail error conditions, permissions, or behavior for large documents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no fluff, efficiently communicating the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description is adequate but lacks context on error handling, pagination, or when to prefer this combined tool over individual siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds some meaning by linking parameters to 'capped markdown and content blocks', but does not explicitly explain each parameter (e.g., task_id, max_blocks, max_markdown_length) or how they interact, leaving gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the specific resource 'task metadata plus capped markdown and content blocks', with the qualifier 'for small documents', which distinguishes it from siblings like get_content_blocks and get_markdown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives like get_content_blocks or get_markdown, nor does it mention prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_markdownC

Return a slice of a task's markdown result.

ParametersJSON Schema
NameRequiredDescriptionDefault
offsetNo
task_idYes
max_lengthNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only states the operation (return a slice) without disclosing side effects, error behavior, or authentication requirements. This is minimal behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single sentence is concise and front-loaded with the core action. However, it could include brief parameter hints without becoming verbose; it is efficient but not maximally informative within the same length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description does not clarify what the output contains (e.g., content string, metadata). The parameters are unexplained, and there is no discussion of edge cases or required context (e.g., task must be processed). This is incomplete for a tool with 3 parameters and no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the property descriptions in the schema are empty. The tool description does not explain the meaning of offset or max_length, which are critical for correct usage. Default values are given but not their semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns a slice of a task's markdown result, using specific verb and resource. However, it does not differentiate from sibling tools like get_full_result or get_content_blocks, missing the highest clarity level.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., get_full_result for the entire markdown). No mention of prerequisites or limitations, leaving the agent without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_task_statusC

Return the current OcrPlane task record for a task id.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description only states read operation ('return') without specifying side effects, auth needs, or output format details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, concise but omits useful details; could add value without increasing length significantly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists but description doesn't reference it; lacks details on return structure, 'current' semantics, or error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only parameter task_id lacks description in schema; description adds minimal context ('for a task id'), not compensating for 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'return' and resource 'OcrPlane task record' identified by task id. Distinguishable from sibling tools like get_content_blocks or list_tasks, though no explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no context on prerequisites or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tasksC

List OcrPlane tasks for the configured API key user.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
limitNo
searchNo
sourceNoapi

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description must disclose behavioral traits. It only mentions scoping to the user's API key but omits details like pagination behavior (though page/limit params exist), rate limits, side effects, or error handling. This is insufficient for a tool with no annotation context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundancy. However, its brevity sacrifices necessary detail; a slightly longer description could provide parameter hints or usage context without being wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema (not provided), the description fails to explain the return structure or pagination logic. For a listing tool with four optional parameters, the description should cover common use cases, such as how search and source affect results, which it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, and the tool description does not explain any of the four parameters (page, limit, search, source) beyond what the schema defines. The description adds no semantic value about their purpose, valid values, or default behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'List', the resource 'OcrPlane tasks', and the scope 'for the configured API key user'. It effectively distinguishes from sibling tools like get_task_status or parse_document by indicating it returns a list rather than a single resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as get_task_status or parse_document. The description does not mention prerequisites, such as needing to have previously uploaded a document, nor does it explain what scenarios favor listing tasks over retrieving specific ones.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
langNoch
waitNo
backendNopipeline
file_urlNo
filenameNo
file_pathNo
end_page_idNo
parse_methodNoauto
table_enableNo
start_page_idNo
base64_contentNo
formula_enableNo
timeout_secondsNo
poll_interval_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It mentions optional waiting and that the initial result is a compact summary, but does not disclose auth needs, rate limits, or details about the submission process.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no fluff, front-loading the core purpose. Could be slightly more structured by grouping parameter details, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 14 parameters and an output schema, the description omits details on most parameters. It provides good guidance on pagination alternatives but lacks parameter semantics, making it incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only explains the mutual exclusivity of file_path, file_url, and base64_content, plus wait. It fails to describe 11 other parameters like backend, parse_method, table_enable, etc.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool submits a document to OcrPlane OCR, specifies required input (file_path, file_url, or base64_content), and distinguishes from sibling tools like get_markdown and get_content_blocks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises preferring file_url for large files and directs users to get_markdown or get_content_blocks for large results, providing clear context and alternatives. No explicit when-not-to-use, but sufficient guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reprocess_taskC

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

ParametersJSON Schema
NameRequiredDescriptionDefault
langNo
rotateNo
backendNo
task_idYes
rotationsNo
page_indicesNo
parse_methodNo
rotate_pagesNo
table_enableNo
formula_enableNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fails to disclose important behavioral traits such as whether reprocessing modifies the task state, is destructive, or requires special permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single-sentence description is concise but too terse given the complexity of 10 parameters and the need for more detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is incomplete: it lacks information about return values (despite output schema existing) and does not cover the full set of parameters or behaviors.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Of 10 parameters, only rotation and re-OCR are hinted; parameters like lang, backend, table_enable, formula_enable are completely unexplained, and schema coverage is 0%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it reprocesses an existing task with optional rotation or re-OCR, which distinguishes it from sibling tools that are read-only or initial parsing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use reprocess_task versus other tools like parse_document or list_tasks, nor any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv0.1.0
    • First observedget_content_blocks
    • First observedget_full_result
    • First observedget_markdown
    • First observedget_task_status
    • First observedlist_tasks
    • First observedparse_document
    • First observedreprocess_task

TDQS

B3.3/5.0
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

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/asharca/ocrplane-cli'

If you have feedback or need assistance with the MCP directory API, please join our Discord server