# Open Ocr Cli

> Provider-neutral multimodal OCR CLI and MCP server for images, PDFs, URLs, structured extraction, and agentic workflows—Gemini, Kimi, Muse, OpenRouter, and Cloudflare AI Gateway.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cyanxxy-open-ocr-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cyanxxy](https://agentstack.voostack.com/s/cyanxxy)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cyanxxy](https://github.com/cyanxxy)
- **Source:** https://github.com/cyanxxy/open-ocr-cli
- **Website:** https://www.npmjs.com/package/open-ocr-cli

## Install

```sh
agentstack add mcp-cyanxxy-open-ocr-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Open OCR CLI

**Agent-first, provider-neutral document extraction for the command line.**

Turn images, PDFs, and public URLs into text or validated structured data —
through Gemini, Kimi K3, Meta Muse Spark, OpenRouter, or any OpenAI-compatible
endpoint — behind one consistent extraction contract.

[](https://github.com/cyanxxy/open-ocr-cli/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/open-ocr-cli)
[](https://github.com/cyanxxy/open-ocr-cli/releases)
[](package.json)
[](LICENSE)

[Quick start](#quick-start) · [Modes](#extraction-modes) · [Commands](#commands) ·
[Agents and MCP](#agents-and-mcp) · [Providers](#providers) ·
[Full CLI reference](packages/cli/README.md)

---

> [!NOTE]
> `open-ocr-cli` is the current executable and npm package; the earlier
> `gemini-ocr` executable and config paths still work. This repository also
> hosts the original Gemini [web app](#web-application) — provider-neutral
> support applies to the CLI.

## Quick start

Requires Node.js **20.19+**, **22.13+**, or **24+** and one provider key
(`--dry-run` needs none).

```bash
npm install --global open-ocr-cli

export GEMINI_API_KEY="your-key"
open-ocr-cli extract invoice.pdf
```

Switch providers with a flag:

```bash
open-ocr-cli extract invoice.pdf --provider kimi          # MOONSHOT_API_KEY
open-ocr-cli extract invoice.pdf --provider openrouter \
  --model moonshotai/kimi-k3                              # OPENROUTER_API_KEY
```

Keys are read only from the environment or a project `.env` — never from a flag
or config file. With no arguments the CLI prints help and never prompts, so
scripts and CI stay deterministic; `interactive`, `init`, and `doctor` cover the
guided paths.

Also available as a [Docker image](packages/cli/README.md#distribution)
(`ghcr.io/cyanxxy/open-ocr-cli`), a [GitHub Action](action.yml)
(`cyanxxy/open-ocr-cli@v2`), and a Homebrew formula.

## Extraction modes

| Mode | Command | Best for |
| --- | --- | --- |
| **Simple** | `extract --mode simple` | General text, layout, equations, image descriptions |
| **Template** | `extract --preset ` | Invoices, receipts, resumes, business cards |
| **Custom schema** | `extract --schema ` | Your own validated JSON structure |
| **Agentic** | `extract --mode agentic` | Iterative field recovery and targeted region re-OCR |
| **Web** | `web ` | Grounded extraction from public URLs |

Schemas are validated locally — both the schema and the model's returned value —
before anything is written. Invalid JSON or a schema mismatch is never persisted
as a success.

Agentic mode uses a two-loop design: an outer document loop evaluates confidence
and coverage, while an inner loop lets the model call one tool (structure
analysis, batch field extraction, region re-OCR), inspect the result, and decide
what to do next. The document is sent once.

## Commands

| Command | Purpose |
| --- | --- |
| `extract ` | Extract files, directories, globs, or binary stdin (`-`) |
| `web ` | Grounded extraction from up to 20 public HTTP(S) URLs |
| `run --request ` | Execute a versioned machine-protocol request |
| `mcp` | Serve OCR tools over the Model Context Protocol stdio transport |
| `capabilities` · `schema` | Advertise providers, modes, limits, error codes; print JSON Schemas |
| `init` · `doctor` · `interactive` | Configure, diagnose, and explore |
| `status [output]` | Audit a completed or interrupted batch |
| `presets` · `models` · `providers` | Discover templates, model IDs, and provider profiles |

```bash
# Recursive, resumable batch
open-ocr-cli extract ./documents --output ./results --concurrency 4 --resume

# Structured invoice artifacts (markdown + JSON + CSV)
open-ocr-cli extract ./invoices --preset invoice --format all --output ./invoice-results

# Validate the full plan without credentials, API calls, or writes
open-ocr-cli extract ./documents --dry-run
```

Extracted content and JSONL events go to `stdout`; progress and diagnostics go
to `stderr` — every command composes safely in a pipeline.

> **Flags, configuration keys, batch semantics, cost controls, and exit codes:**
> [packages/cli/README.md](packages/cli/README.md)

## Agents and MCP

Three entry points wrap the same job engine.

**Machine protocol** — `run` executes a versioned request (v2 current, v1 still
supported) validated against published Draft 2020-12 JSON Schemas, returning a
typed result object or an ordered JSONL event stream with stable sequence
numbers and typed error codes carrying recovery hints:

```bash
open-ocr-cli capabilities --json
open-ocr-cli run --request request.json --response-format jsonl
```

**MCP server** — `open-ocr-cli mcp` starts a stdio server exposing
`ocr_extract`, `ocr_run_agentic`, and `ocr_web`, plus an
`open-ocr://capabilities` resource:

```json
{
  "mcpServers": {
    "open-ocr": {
      "command": "open-ocr-cli",
      "args": ["mcp"]
    }
  }
}
```

**Agent skill** — a validated skill for Claude Code, Codex, and compatible
agents ships at
[`integrations/open-ocr/skills/open-ocr/SKILL.md`](integrations/open-ocr/skills/open-ocr/SKILL.md)
and in the npm package under `skills/open-ocr/`.

All three are reference-first: large bodies land in `.open-ocr-results/`
artifacts instead of flooding an agent's context, cancellation is honored, and
under `mcp` stdout carries only transport messages.

## Providers

| Profile | Default model | Documents | Structured output | Agent tools |
| --- | --- | --- | --- | --- |
| `gemini` | `gemini-3.5-flash` | Images and native PDFs | Yes | Native Interactions API |
| `kimi` | `kimi-k3` | Images; PDFs via Kimi file extraction | Yes | OpenAI-compatible tool calls |
| `muse` | `muse-spark-1.1` | PNG, JPEG, WebP, GIF, PDF | Yes | OpenAI-compatible tool calls |
| `openrouter` | `google/gemini-3.5-flash` | Model-dependent | Model-dependent | Model-dependent |
| `openai-compatible` | Required | Images; PDF not assumed | Endpoint-dependent | Endpoint-dependent |

Named profiles supply endpoints, credential variable names, and multimodal wire
formats; `openrouter` and `openai-compatible` take arbitrary upstream model IDs.
Any provider can also run through **Cloudflare AI Gateway** with `--gateway
cloudflare`, including BYOK.

Model catalogs, reasoning levels, cost estimates, and gateway configuration are
documented in the [CLI reference](packages/cli/README.md#models-reasoning-and-cost).

## Limits and guarantees

| Constraint | Limit |
| --- | --- |
| Formats | PNG · JPEG · WebP · GIF · HEIC · HEIF · PDF (video is rejected) |
| Size | Images 70 MB raw · PDFs 50 MB and 1,000 pages |
| Batches | 1,000 files and 5,120 MB by default; concurrency 1–16 |
| Output | Markdown · JSON · CSV · JSONL · agent audit steps |

Every discovered input gets a succeeded, partial, failed, or skipped result —
no silent loss. Batches are fingerprinted and resumable, output is lock-guarded
and no-clobber, and truncated, blocked, or schema-invalid model responses fail
closed rather than being written as success.

There is no backend and no telemetry: documents go to the selected provider or
gateway and nowhere else. Web OCR rejects credentials in URLs, localhost,
private ranges, and tunnel hosts, and pins DNS across redirects. Report
vulnerabilities privately via [SECURITY.md](SECURITY.md).

## Web application

The repository also contains the original Gemini-powered React app with the same
five workflows and light/dark/AMOLED themes:

```bash
npm ci && npm run dev   # http://localhost:5173 — add your key under Settings
```

> [!IMPORTANT]
> The browser stores the API key in `localStorage` with light obfuscation, not
> strong encryption. Anyone with access to that browser profile can recover it.
> Prefer a backend proxy for organization-owned credentials.

## Repository layout

One repository, three entry points over a shared extraction engine:

| Path | What it is |
| --- | --- |
| `src/lib` | The engine: providers, extraction modes, agent loop, protocol types. No browser APIs, so both front ends use it. |
| `src/` (rest) | The React web app — the `npm run dev` target described above. |
| `packages/cli` | The published `open-ocr-cli` npm package. Owns its own source, build, and protocol schemas. |
| `integrations/open-ocr/skills` | Agent skill definitions. Source of truth; `packages/cli/skills` is a generated copy. |
| `evals/` | The evaluation corpus and runner. |

`open-ocr-cli mcp` is not a separate package — it is a third front end inside
the CLI, alongside `extract` (human-facing) and `run` (versioned protocol), all
routed through the same job service.

The CLI is typechecked without DOM libraries on purpose, so a browser API cannot
reach it through the shared engine.

## Contributing

Setup, PR gates, and release steps are in [CONTRIBUTING.md](CONTRIBUTING.md).
Behavior changes need tests or evaluation evidence; the evaluation suite is
documented in [evals/README.md](evals/README.md).

[Issues](https://github.com/cyanxxy/open-ocr-cli/issues) ·
[Releases](https://github.com/cyanxxy/open-ocr-cli/releases) ·
[Changelog](CHANGELOG.md) · [Security](SECURITY.md) ·
[Code of Conduct](CODE_OF_CONDUCT.md)

**MIT Licensed** — see [LICENSE](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cyanxxy](https://github.com/cyanxxy)
- **Source:** [cyanxxy/open-ocr-cli](https://github.com/cyanxxy/open-ocr-cli)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/open-ocr-cli

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cyanxxy-open-ocr-cli
- Seller: https://agentstack.voostack.com/s/cyanxxy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.