superpdf

<div align="center">

<h1>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/superpdf-logo-horizontal-on-dark.svg">
    <img src="docs/assets/superpdf-logo-horizontal.svg" alt="superPDF AI" width="300">
  </picture>
</h1>

### superPDF AI: PDF tools that run on your computer, from the command line, Python, AI assistants (MCP) or a local API.

**Tables, charts, headings and scans to Markdown, HTML or JSON; Word, Excel and PowerPoint; forms, merging and comparing. The reader works by rules, not a language model; scans go through Tesseract OCR. Nothing is uploaded.**

[![CI](https://img.shields.io/github/actions/workflow/status/arjunprabhulal/superpdf/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/arjunprabhulal/superpdf/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@superpdf/cli?style=flat-square&color=4338ca)](https://www.npmjs.com/package/@superpdf/cli) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-555555?style=flat-square)](LICENSE) [![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org) [![MCP server](https://img.shields.io/badge/MCP-server-4338ca?style=flat-square)](#use-it-from-your-ai-assistant-mcp)

**[Website](https://superpdf.ai) · [Docs](https://superpdf.ai/docs/mcp-api/command-line-tools) · [Python docs](https://superpdf.ai/docs/python) · [Benchmark](https://superpdf.ai/performance) · [Changelog](CHANGELOG.md)**

[How it compares](#how-it-compares) · [Quick start](#quick-start) · [JavaScript/TypeScript](#use-it-from-javascript-or-typescript) · [Python](#use-it-from-python) · [MCP tools](#mcp-tools) · [How it works](#how-it-works)

<code>npx @superpdf/cli export report.pdf --output report.md</code>

<br><br>

<img src="docs/assets/demo.gif" alt="Claude Code with the superPDF MCP server: asked to combine two invoices and list their vendor, number, due date and total, it calls superPDF three times and answers with the table" width="1000">

</div>

---

superPDF reads a PDF the way it was made: from the text, fonts and drawings inside it. It rebuilds the document as
Markdown, HTML or JSON, with headings at the right level, tables with their rows and columns, and charts turned back
into the numbers they were drawn from. Scanned pages are read with OCR in 15 languages.

It runs on your computer as a command, a Python package, an MCP server for AI assistants such as Claude Code, Cursor
and Codex, or a local REST API for your own scripts. It only opens files in the folders you allow and never uploads them
(through MCP, the text your assistant reads goes to its model, as with any file you show it). It is the same reader
that powers [superpdf.ai](https://superpdf.ai) in the browser.

| Use it as | Install or run | Docs |
|---|---|---|
| Command line | `npm install -g @superpdf/cli`, or `npx @superpdf/cli …` without installing | [CLI](https://superpdf.ai/docs/mcp-api/command-line-tools) |
| Command line with Homebrew | `brew install arjunprabhulal/superpdf/superpdf` | [Tap](https://github.com/arjunprabhulal/homebrew-superpdf) |
| MCP server for AI assistants | `superpdf mcp --allow-dir ~/Documents/superPDF` | [MCP setup](https://superpdf.ai/docs/mcp-api/mcp-tool-access) |
| Local REST API (OpenAPI 3.1) | `superpdf serve --allow-dir ~/Documents/superPDF` | [API](https://superpdf.ai/docs/api) |
| JavaScript and TypeScript SDK | `npm install @superpdf/cli`, then `import { toDocx } from '@superpdf/cli'` | [SDK](#use-it-from-javascript-or-typescript) |
| Python SDK | `pip install superpdf` or `uv add superpdf` | [Python](https://superpdf.ai/docs/python) |
| Python, without installing | `uvx superpdf …` or `pipx run superpdf …` | [Python](https://superpdf.ai/docs/python#command) |
| LangChain | `pip install langchain-superpdf` | [Loader](https://superpdf.ai/docs/python/langchain-llamaindex#langchain) |
| LlamaIndex | `pip install llama-index-readers-superpdf` | [Reader](https://superpdf.ai/docs/python/langchain-llamaindex#llamaindex) |
| LangGraph agents | the MCP server through `langchain-mcp-adapters` | [Agents](https://superpdf.ai/docs/python/langchain-llamaindex#langchain-agents) |

## How it compares

On [ParseBench](https://www.parsebench.ai), in **our own run** of its open-source test suite on all 2,078 documents,
superPDF scores **65.0** overall (64.8 on documents it was never tuned on). It is not on the official leaderboard yet.
The other scores are a selection from the public leaderboard (October 12, 2026).

| Parser | Overall | Tables | Charts | Content | Formatting | Grounding |
|---|---|---|---|---|---|---|
| LlamaParse Agentic Plus (paid service) | 90.2 | 93.4 | 94.2 | 92.3 | 87.1 | 84.1 |
| Claude Opus 5.5 (AI model) | 78.0 | 93.9 | 64.1 | 91.8 | 77.0 | 63.2 |
| **superPDF** (no language model, our run) | **65.0** | 68.4 | 52.2 | 80.5 | 62.3 | 61.5 |
| Azure Document Intelligence | 59.6 | 86.0 | 1.6 | 84.9 | 51.9 | 73.8 |
| Docling (docling-models) | 50.6 | 66.4 | 52.8 | 66.9 | 1.0 | 66.1 |
| Google Cloud Document AI | 50.4 | 55.1 | 1.4 | 83.7 | 50.5 | 61.3 |
| AWS Textract | 47.9 | 84.6 | 6.0 | 74.8 | 3.7 | 70.4 |

Compared with the Azure, Google and AWS services, superPDF scores much higher on charts and higher on formatting; Azure and
Textract score higher on tables. LlamaParse and Claude Opus 5.5 score higher overall. Full table and method:
[superpdf.ai/performance](https://superpdf.ai/performance).

## Quick start

You need [Node.js](https://nodejs.org) 22 or later.

### Use it from the terminal

```bash
npx @superpdf/cli export report.pdf --output report.md
```

npx downloads the tool once and runs it. To install the `superpdf` command for regular use:

```bash
npm install -g @superpdf/cli
superpdf help
```

Or with Homebrew on macOS or Linux, which brings its own Node.js:

```bash
brew install arjunprabhulal/superpdf/superpdf
```

### Use it from your AI assistant (MCP)

Create the folder the assistant may use, then add the server. For Claude Code:

```bash
mkdir -p ~/Documents/superPDF
claude mcp add --scope user superpdf -- npx -y @superpdf/cli mcp --allow-dir ~/Documents/superPDF
```

For Cursor, Claude Desktop and other assistants that read an MCP settings file:

```json
{
  "mcpServers": {
    "superpdf": {
      "command": "npx",
      "args": ["-y", "@superpdf/cli", "mcp", "--allow-dir", "/Users/you/Documents/superPDF"]
    }
  }
}
```

With the command installed (`npm install -g @superpdf/cli`), use `superpdf mcp --allow-dir …` in place of
`npx -y @superpdf/cli mcp --allow-dir …`. Then ask, for example: *"Read invoice.pdf in my superPDF folder and give me
the line items as a table."* The assistant can only use the folders you pass with `--allow-dir`. Setup for each
assistant: [superpdf.ai/docs/mcp-api/mcp-tool-access](https://superpdf.ai/docs/mcp-api/mcp-tool-access).

### Use it from Python

```bash
pip install superpdf                 # or run without installing: uvx superpdf export report.pdf --output report.md
```

```python
import superpdf

markdown = superpdf.export("report.pdf")
pages = superpdf.export_pages("report.pdf")        # Markdown per page

superpdf.merge(["a.pdf", "b.pdf"], "combined.pdf")  # every tool is a typed function
superpdf.extract_tables("report.pdf", "tables.xlsx")
superpdf.to_docx("report.pdf", "report.docx")

from superpdf.langchain import SuperPDFLoader       # pip install "superpdf[langchain]"
docs = SuperPDFLoader("report.pdf").load()
```

Node.js comes with the package. All 30 tools, a LlamaIndex reader and the full reference are in the
[Python docs](https://superpdf.ai/docs/python) and [python/README.md](python/README.md).

### Use it from JavaScript or TypeScript

```bash
npm install @superpdf/cli
```

```ts
import { exportPages, extractTables, toDocx, SuperPDFError } from '@superpdf/cli';

const pages = await exportPages('report.pdf');          // [{ page: 1, markdown: '# Quarterly report…' }]
const word = await toDocx({ input: 'report.pdf', output: 'report.docx' });
await extractTables({ input: 'report.pdf', format: 'csv', output: 'tables.csv' });
```

Every tool is an async function (`merge`, `split`, `fillForm`, `compare`, `runBatch` and the rest; `tools()` lists
them) that takes the tool's JSON input and returns its typed result. It runs in your Node.js process (22 or later):
no server, no subprocess. TypeScript types come with the package, generated from the same schemas as the MCP server
and the API. Errors are `SuperPDFError` with a `code` (`validation`, `conflict`, `not_found`, `operation_failed`).
Each call may only use the folders of the paths you give it, or the ones you pass as `{ allowDirs }`.

### Use it from your own code (REST API)

```bash
superpdf serve --allow-dir ~/Documents/superPDF
```

This starts a private API on `127.0.0.1` that only this computer can reach. It prints a token when it starts (or set
`SUPERPDF_API_TOKEN`, at least 32 characters); every request under `/v1/` needs it. The OpenAPI 3.1 document is served at `/openapi.json` (also
[openapi.json](openapi.json) here, generated from the tool schemas). Guide and reference:
[superpdf.ai/docs/api](https://superpdf.ai/docs/api).

## What it reads

<img src="docs/assets/pdf-to-markdown.png" alt="Input: a one-page report PDF with a table and a bar chart. Output: the Markdown superPDF writes from it, with the heading levels, the table, and the chart's values as a table" width="1000">

| Part of the PDF | How superPDF reads it |
|---|---|
| **Tables** | Ruled tables from their lines (shading inside them splits rows), borderless tables from aligned text; `--tables html` keeps merged header cells |
| **Charts** | Bar, line, dot, area and pie charts drawn as shapes, turned into tables of values; values measured from the drawing, not printed on it, are marked approximate |
| **Structure** | Headings and their levels, paragraphs, lists, bold and italic text, page headers and footers |
| **Reading order** | Mult