okrapdf

Open a local PDF parser dashboard with one command.

npx okrapdf report.pdf

The dashboard runs on 127.0.0.1. It shows the PDF and the parsed output side by side, with Preview, Blocks, Markdown, JSON, and Raw views. Hover a box in the PDF to find its block, or hover a block to find its box. The two panes scroll together.

Run npx okrapdf with no file for a drop zone and a sample document. The sample is from the FY 2024 Financial Report of the U.S. Government, a public document.

No account is necessary. Your document stays on your computer until you choose a cloud model, and then only the pages that you parse go to that provider.

Models

| Source | How to use it | | --- | --- | | Text layer | Runs first, with no model. It reads text PDFs and returns nothing for scans. | | Local servers | The dashboard finds Ollama, LM Studio, vLLM, llama.cpp, MLX, and Jan on their default ports. | | LlamaParse | Set LLAMA_CLOUD_API_KEY, or add a key in the Models tab. The Agentic, Cost Effective, and Agentic Plus tiers appear in the model menu, and the dashboard shows the credits that a run uses. | | Your API key | Set GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, or NVIDIA_API_KEY, or add a key in the Models tab. | | Other servers | Add any OpenAI-compatible base URL in the Models tab. |

Keys stay in the local server. A key that you save goes to ~/.okra/dashboard-secrets.json with 0600 permissions.

ParseBench

Each model run uses the parse_with_layout prompts from ParseBench word for word. OCR-class models (DeepSeek-OCR, dots.ocr, Chandra, Infinity-Parser2) use their own formats.

The Bench tab parses pages from the ParseBench dataset with your model. The official parse-bench package then gives the five scores: tables, charts, content faithfulness, semantic formatting, and visual grounding. Scoring needs uv. The dashboard does not have its own copy of the metrics.

The 12-page sample is a quick check. Only the full 2,000-page run compares with the published leaderboard. LlamaParse is not a bench model here, because its scores are on that leaderboard.

npx okrapdf bench --model gemini/gemini-3-flash-preview
npx okrapdf bench --model ollama/qwen3-vl:4b --full

Commands for agents

npx okrapdf report.pdf --background --json   # start, print the URL, and return
npx okrapdf model --json                     # list local models and keys
npx okrapdf parse report.pdf --model ollama/qwen3-vl:4b --pages 1-3 --json
npx okrapdf parse report.pdf --model llamaparse/agentic --pages 1-3 --json
npx okrapdf context                          # read the block selected in the dashboard
npx okrapdf status
npx okrapdf stop

A background dashboard stops after 30 idle minutes. Any other command goes to the okra cloud CLI, @okrapdf/cli.

MCP server for agents

npx okrapdf mcp serves the same local parser as MCP tools over stdio. It runs on your computer, with the same models and keys as the dashboard. Nothing leaves your computer unless you pick a cloud model that runs on your own key.

| Tool | What it does | | --- | --- | | parse_pdf | Parse a PDF into blocks, each with its page and box. Default model: the text layer (free and offline). | | find_in_pdf | Find a quote or a number and return each block that holds it, with page and box. | | list_models | List local models, configured keys, and a local vision model that fits this computer. | | open_dashboard | Open the dashboard with the PDF beside its blocks. | | get_selected_block | Read the block that the person clicked in the dashboard. |

The okraPDF viewer in Codex and ChatGPT desktop

The server also includes a viewer as an MCP App with OpenAI plugin extensions:

• Open in → okraPDF: a .pdf file in a thread opens in the okraPDF viewer, with its blocks drawn on each page.
• okraPDF tab: add okraPDF from the new-tab page (More tools) to open a tab beside the thread with the PDFs that okraPDF has opened.
• open_pdf_viewer: the agent opens a PDF in the viewer by path.

Hover a block to see it on the page. Click a block to attach it to the chat as context, with its page, block id, and box. Ask about this block sends a question about it. The page images come from the local server, so the PDF stays on your computer.

Add it to any MCP client:

{
  "mcpServers": {
    "okrapdf": { "command": "npx", "args": ["-y", "okrapdf@^0.18.0", "mcp"] }
  }
}

The okracomputer/skills plugin adds this server and the okrapdf skill to Codex, ChatGPT desktop, Claude Code, Cursor, and VS Code in one install.

Library

The client library moved to @okrapdf/sdk. Versions before 0.15.0 of this package hold the old library.

License

MIT. PDF rendering uses mupdf, which has an AGPL-3.0 license and installs as a separate dependency.