superPDF AI

---

superPDF 按照 PDF 的制作方式读取文件：从其中的文本、字体和图形着手。它会将文档重建为 Markdown、HTML 或 JSON，保留正确层级的标题、包含行和列的表格，并将图表还原为其绘制所依据的 数据。扫描页面会通过 OCR 识别，支持 15 种语言。

它可以在本机作为命令、Python 包、供 Claude Code、Cursor 和 Codex 等 AI 助手使用的 MCP 服务，或供你自己的脚本调用的本地 REST API 运行。它只会打开你授权的文件夹中的文件，绝不会上传文件 （通过 MCP 使用时，助手读取的文本会发送给其模型，这与向助手展示任何文件时的情况相同）。它与浏览器中的 superpdf.ai 使用的是同一款阅读器。

使用方式	安装或运行	文档
命令行	npm install -g @superpdf/cli，或使用 npx @superpdf/cli …，无需安装	CLI
使用 Homebrew 的命令行	brew install arjunprabhulal/superpdf/superpdf	Tap
AI 助手的 MCP 服务	superpdf mcp --allow-dir ~/Documents/superPDF	MCP 设置
本地 REST API（OpenAPI 3.1）	superpdf serve --allow-dir ~/Documents/superPDF	API
JavaScript 和 TypeScript SDK	npm install @superpdf/cli，然后运行 import { toDocx } from '@superpdf/cli'	SDK
Python SDK	pip install superpdf 或 uv add superpdf	Python
无需安装即可使用 Python	uvx superpdf … 或 pipx run superpdf …	Python
LangChain	pip install langchain-superpdf	加载器
LlamaIndex	pip install llama-index-readers-superpdf	阅读器
LangGraph Agent	通过 langchain-mcp-adapters 使用 MCP 服务	Agent

对比情况

在 ParseBench 上，我们自行运行其开源测试套件，对全部 2,078 份文档进行测试，superPDF 的总分为 65.0（在从未用于调优的文档上得分为 64.8）。目前它尚未登上官方排行榜。 其他分数选自公开排行榜（2026 年 10 月 12 日）。

解析器	总分	表格	图表	内容	格式	溯源
LlamaParse Agentic Plus（付费服务）	90.2	93.4	94.2	92.3	87.1	84.1
Claude Opus 5.5（AI 模型）	78.0	93.9	64.1	91.8	77.0	63.2
superPDF（不使用大模型，运行结果）	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

与 Azure、Google 和 AWS 的服务相比，superPDF 的图表得分高出许多，格式得分也更高；Azure 和 Textract 的表格得分更高。LlamaParse 和 Claude Opus 5.5 的总分更高。完整表格和方法说明： superpdf.ai/performance。

快速开始

你需要 Node.js 22 或更高版本。

在终端中使用

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

npx 会下载该工具并运行。若要安装 superpdf 命令以便日常使用：

npm install -g @superpdf/cli
superpdf help

也可以在 macOS 或 Linux 上使用 Homebrew，它会自带 Node.js：

brew install arjunprabhulal/superpdf/superpdf

在 AI 助手中使用（MCP）

创建助手可以使用的文件夹，然后添加服务。以 Claude Code 为例：

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

对于 Cursor、Claude Desktop 以及其他读取 MCP 设置文件的助手：

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

安装命令后（npm install -g @superpdf/cli），可使用 superpdf mcp --allow-dir …，代替 npx -y @superpdf/cli mcp --allow-dir …。然后可以这样提问："读取我的 superPDF 文件夹中的 invoice.pdf，并将明细项目整理成表格。" 助手只能使用你通过 --allow-dir 指定的文件夹。各助手的设置说明： superpdf.ai/docs/mcp-api/mcp-tool-access。

在 Python 中使用

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

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。全部 30 个工具、LlamaIndex 阅读器和完整参考文档请参阅 Python 文档和 python/README.md。

在 JavaScript 或 TypeScript 中使用

npm install @superpdf/cli

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' });

每个工具都是异步函数（merge、split、fillForm、compare、runBatch 等；tools() 会列出 所有工具），接收工具的 JSON 输入并返回类型化结果。它在你的 Node.js 进程中运行（22 或更高版本）： 无需服务，也无需子进程。软件包自带 TypeScript 类型，这些类型与 MCP 服务和 API 使用相同的架构生成。 错误类型为 SuperPDFError，带有 code（validation、conflict、not_found、operation_failed）。 每次调用只能使用你提供的路径所在文件夹，或通过 { allowDirs } 传入的文件夹。

在自己的代码中使用（REST API）

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

这会在 127.0.0.1 上启动一个仅此计算机可访问的私有 API。启动时会打印令牌（也可以设置 SUPERPDF_API_TOKEN，长度至少为 32 个字符）；每个 /v1/ 下的请求都需要该令牌。OpenAPI 3.1 文档可通过 /openapi.json 访问（此处也有 openapi.json，由工具架构生成）。指南和参考文档： superpdf.ai/docs/api。

可读取的内容

PDF 内容	superPDF 的读取方式
表格	根据线条识别带边框的表格（表格内部的底纹会分隔行），根据文本对齐识别无边框表格；--tables html 可保留合并的表头单元格
图表	将以形状绘制的柱状图、折线图、点图、面积图和饼图转换为数值表格；从图形中测量而非直接印出的数值会标记为约数
结构	标题及其层级、段落、列表、粗体和斜体文本、页眉和页脚
阅读顺序	按列间空隙拆分多栏页面，使文本按顺序阅读
扫描件	使用 Tesseract OCR 识别没有文本层的页面，支持英语和另外 14 种语言；语言数据已随软件打包，无需下载
大文件	页数不限；文件最大支持 2 GB

命令

superpdf info document.pdf                                    # pages, sizes, form fields, properties
superpdf merge a.pdf b.pdf --output combined.pdf
superpdf extract document.pdf --pages 1,3-5 --output selected.pdf
superpdf rotate document.pdf --pages 2 --angle 90 --output rotated.pdf
superpdf export document.pdf --output document.md             # or .html / .json (--format)
superpdf export document.pdf --tables html --output doc.md    # tables as HTML, keeping merged header cells
superpdf export https://example.com/a.pdf --output a.md       # a PDF from an https:// link
superpdf convert report.docx --output report.pdf              # Word, Excel, PowerPoint; needs LibreOffice
superpdf pipeline document.pdf --steps steps.json --output result.pdf
superpdf audio document.pdf --output document.m4a             # read aloud with the macOS system voice
superpdf tools                                                # all 30 tools with their JSON input schemas
superpdf tool pdf_protect --input '{"input":"a.pdf","password":"…","output":"locked.pdf"}'   # any tool, JSON in and out

结果始终写入新文件；绝不会覆盖现有文件。superpdf help 会显示所有命令。 可以对 examples/quarterly-report.pdf 这个单页报告试用 info 和 export。

export 还可以读取 https:// 链接：文件最大支持 2 GB；无数据传输超过 60 秒后停止，并且最多跟随 5 次重定向。每次重定向都会拒绝指向本机或本地网络（localhost、私有地址和链路本地地址）的链接，也会拒绝非 PDF 文件；读取完成后会删除下载的文件。只有 export 接受链接；mcp、serve 和 tool 只读取其 --allow-dir 文件夹中的文件。

MCP 工具

工具	功能
pdf_list_files	列出允许访问的文件夹中的 PDF
pdf_info	页数、页面尺寸、表单字段和属性
pdf_read_text	逐页读取嵌入的文本
pdf_extract_structure	提取包含标题、表格、图表和列表的 Markdown、HTML 或 JSON
pdf_merge、pdf_split、pdf_extract_pages、pdf_remove_pages	将页面合并或拆分为新的 PDF
pdf_extract_tables	将表格和矢量图表导出为 Excel、CSV、JSON 或 Markdown
pdf_outline、pdf_compare	提取包含各章节页码的大纲；逐页比较两个版本之间的差异
pdf_to_docx、pdf_to_pptx、pdf_to_epub	转换为可编辑的 Word、PowerPoint（文本作为文本框）和 EPUB 3
pdf_from_images、pdf_from_markdown	将 JPG 和 PNG 图像或 Markdown 文件转换为 PDF
pdf_fill_form、pdf_flatten	按名称填写表单字段；将字段合并到页面中
pdf_add_text、pdf_resize_pages	添加键入的签名和备注；裁剪页边距或缩放页面
pdf_rotate_pages、pdf_add_page_labels、pdf_add_watermark	旋转页面、添加页码（页眉或页脚）以及添加水印
pdf_protect、pdf_unlock、pdf_remove_metadata、pdf_repair	设置 AES-256 密码、清理属性、修复损坏的文件
pdf_from_office	将 Word、Excel 和 PowerPoint 转换为 PDF（需要 LibreOffice）
pdf_run_pipeline、pdf_run_batch	对一个 PDF 执行最多 10 个步骤，或对最多 50 个 PDF 执行相同步骤

它的不同之处

大多数 PDF 转文本工具会提取文本层并按位置排序，或者对页面图像运行 AI 模型。 superPDF 直接处理 PDF 自身的绘制指令，因此能保留精确的文本和位置，并恢复这两种方法往往会丢失的内容：

• 图表会变成数据。 柱形、线条、点、面积和饼图扇区都是以形状绘制的；pdf-charts.js 会根据坐标轴标签（如果没有坐标轴，则根据图表上标出的值）测量柱形、线条、点和面积，根据角度读取饼图扇区，并根据图例颜色匹配数据系列。对于以图片保存的图表，则会退而读取柱形的像素。
• 丢失的字母会被恢复。 如果字体没有正确的 Unicode 表，PDF.js 会将其中的字母读取为空白或直接省略。pdf-text-fixes.js 会将每个字形的轮廓与已识别的字母进行匹配，并根据标准 Mac 字形顺序检查 TrueType 字体，然后补回字母。
• 粗体靠测量，不靠猜测。 字体名称通常是隐藏的（F1、g_d0_f2），因此 pdf-structure.js 会测量字形的笔画粗细、比较同一字体两种字重的宽度，并检测为了呈现粗体而重复绘制或描边的文本。对于扫描件，它会测量每个词的墨迹粗细。
• 间距和隐藏文本会得到修正。 通过测量页面绘制的字形，移除 PDF.js 在字符间距较大的词语中以及中文和日文字符周围插入的错误空格；不保留矩形裁剪区域之外绘制的文本，并修正字母顺序颠倒的阿拉伯语 lam-alef 连字。
• 仅在需要时进行 OCR。 适用于整页扫描件、字体编码乱码的页面，以及包含文本的图片（会先检查是否有类似字母的形状，以免照片产生噪声）。语言由 PDF 的语言标签或文本本身确定；如果识别效果不佳，则使用 Sauvola 阈值法重试。
• 三种方式提取表格。 通过表格线提取、从扫描页像素中识别线条，以及根据文本对齐列提取无边框表格（适用于有文本层的页面）。

工作原理

1. 读取。 PDF.js 会提取文本及其字体和位置，以及绘图操作（线条、矩形、曲线）。
2. 识别。 扫描件或乱码页面，以及包含文本的图片，都会通过 Tesseract OCR 处理。
3. 修复。 从字形轮廓恢复没有 Unicode 映射的字母，并修正间距。
4. 重建。 根据规则将文本归入行和文本块，查找表格网格和无边框列，根据图形形状和坐标轴标签读取图表，根据字体确定标题大小，并按阅读顺序排列各列。
5. 写入。 输出 Markdown、HTML 或 JSON；JSON 会保留每个文本块所在的页面和位置。

读取器位于 lib/：pdf-structure.js（将页面转换为文本块）、pdf-layout.js（行、表格、阅读顺序）、pdf-charts.js（图表）和 pdf-text-fixes.js（文本修复）。改编自 pdfplumber、Camelot、tabula-java 等项目的构想均已在 NOTICE 中注明。

隐私与安全

• 所有操作都在你的计算机上运行。superPDF 唯一发出的网络请求是你为 API 配置的任务回调（webhook）；OCR 语言数据已包含在软件包中。
• MCP 服务和 API 仅在 --allow-dir 文件夹内读取和写入；路径会通过符号链接解析，因此无法越出这些文件夹。
• API 仅监听 127.0.0.1，且 /v1/ 下的每个请求都必须携带 bearer 令牌。
• 输出会写入新文件，不会覆盖已有文件。

发现安全问题？请参阅 SECURITY.md。

参与贡献

欢迎提交问题和拉取请求。如果遇到读取问题，请附上 PDF（或其中的一页）以及你期望的输出。请参阅 CONTRIBUTING.md。

许可证

Apache-2.0。改编创意和捆绑数据的致谢信息见 NOTICE。“superPDF”及其徽标是本项目的标志，不受该许可证约束。