pdf-table-pull-lite

pdf-table-pull-lite

免费，无需 API 密钥。在你自己的电脑上运行，因此 PDF 文件始终留在你这里。

这款工具可以从文本 PDF 中提取表格，并将每个表格保存为一个 CSV 文件。 需要 Excel 输出、扫描版 PDF，或跨页合并表格？付费版可以满足这些需求：在 Gumroad 上购买 pdf-table-pull

在你自己的电脑上运行，因此 PDF 文件绝不会上传到任何地方。采用 MIT 许可证。支持 Windows、Mac 和 Linux，需要 Python 3.10 或更高版本。

安装

pip install pdf-table-pull-lite

也可以使用 pipx，将它安装在独立环境中：

pipx install pdf-table-pull-lite

想改用 GitHub 上的最新代码？

pip install git+https://github.com/tidybytetools/pdf-table-pull-lite

使用方法

pdf-table-pull-lite statement.pdf                 # CSVs go in statement_tables/
pdf-table-pull-lite statement.pdf -o out/ -p 2-5  # only pages 2 to 5
pdf-table-pull-lite statement.pdf -s text         # tables with no border lines

运行示例：

Found 2 table(s).
  page1_table1: 2 rows x 3 columns
  page1_table2: 2 rows x 2 columns
Saved: statement_tables/page1_table1.csv
Saved: statement_tables/page1_table2.csv

每个表格会生成一个 CSV 文件，并以其所在页码命名。CSV 文件可直接用 Excel 打开（文件以带 BOM 的 UTF-8 格式保存，因此重音符号能正确显示）。

--strategy（-s）：lines 用于带边框的表格，text 用于按间距对齐的表格，auto（默认值）会先尝试 lines，再尝试 text。

在终端中运行时，程序结束前会显示一条关于付费版的简短提示。使用 --quiet 可关闭此提示；通过管道传输或重定向输出时则不会显示。

已知限制

• 扫描版 PDF。 仅包含图像、没有文本层的页面会被跳过，工具会告知你哪些页面被跳过。
• 跨页表格会拆分为多个 CSV 文件，每页一个。
• 特殊布局。 合并单元格或列划分不清晰的表格可能会出现单元格错位。请检查 CSV 文件。
• 仅支持 CSV。 不支持 Excel 或 JSON 输出，也不会清理数字格式（因此 (40) 会保留为文本），且不支持受密码保护的 PDF。

Lite 版与付费版对比

	lite（免费）	pdf-table-pull
文本 PDF，支持带边框或按间距对齐的表格	是	是
CSV 输出	是	是
Excel（每个表格对应一个工作表）和 JSON 输出	否	是
扫描版 PDF（OCR）	否	是
合并跨页表格	否	是
清理数字格式（1,200 → 1200，(40) → -40）	否	是
受密码保护的 PDF	否	是

与其他免费工具的比较

这些工具都免费且开源。选择适合你的工具。

	pdf-table-pull-lite	pdfplumber	Camelot	tabula-py
类型	命令行工具	Python 库	Python 库 + CLI	Tabula 的 Python 封装
需要 Java	否	否	否	是
一条命令即可获取 CSV	是	否，需要编写代码	是	是
自动选择边框或间距模式	是（auto）	否	否	是（guess）
告知哪些页面是扫描件	是	否	否	否
内置供 AI 应用使用的 MCP 服务	是	否	否	否
丰富的调优选项	否	是	是	一些

此工具基于 pdfplumber 构建。如果你想在自己的代码中完全掌控处理过程，请直接使用 pdfplumber 或 Camelot。

在 AI 应用中使用（MCP）

内置了一个小巧的免费 MCP 服务。它为你的 AI 应用提供一个工具：extract_pdf_tables。无需 API 密钥或账户。它需要 uv，该工具会提供 uvx 命令。

手动运行，检查它是否能启动（它会安静地等待应用与其通信）：

uvx --from pdf-table-pull-lite pdf-table-pull-lite-mcp

更简短的启动同一服务的方式：uvx pdf-table-pull-lite mcp。

选择下方的应用并复制代码块。保存后重启应用。

Claude Desktop

打开 Settings > Developer > Edit Config。这会打开 claude_desktop_config.json。添加以下内容：

{
  "mcpServers": {
    "pdf-table-pull-lite": {
      "command": "uvx",
      "args": ["--from", "pdf-table-pull-lite", "pdf-table-pull-lite-mcp"]
    }
  }
}

如果 Claude 提示找不到 uvx，请运行 which uvx（Mac/Linux）或 where uvx（Windows），然后将完整路径填入 "command"。

Cursor

将同一代码块放入 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "pdf-table-pull-lite": {
      "command": "uvx",
      "args": ["--from", "pdf-table-pull-lite", "pdf-table-pull-lite-mcp"]
    }
  }
}

VS Code

VS Code 使用 servers，而非 mcpServers。将以下内容放入项目中的 .vscode/mcp.json，或运行 MCP: Open User Configuration，以便在所有项目中使用：

{
  "servers": {
    "pdf-table-pull-lite": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "pdf-table-pull-lite", "pdf-table-pull-lite-mcp"]
    }
  }
}

或者运行一条命令添加：

code --add-mcp '{"name":"pdf-table-pull-lite","type":"stdio","command":"uvx","args":["--from","pdf-table-pull-lite","pdf-table-pull-lite-mcp"]}'

Cline

在 Cline 面板中，点击 MCP Servers 图标，打开 Configure，然后点击 Configure MCP Servers。在 mcpServers 中添加以下内容：

{
  "mcpServers": {
    "pdf-table-pull-lite": {
      "command": "uvx",
      "args": ["--from", "pdf-table-pull-lite", "pdf-table-pull-lite-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Codex

一条命令：

codex mcp add pdf-table-pull-lite -- uvx --from pdf-table-pull-lite pdf-table-pull-lite-mcp

或者将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.pdf-table-pull-lite]
command = "uvx"
args = ["--from", "pdf-table-pull-lite", "pdf-table-pull-lite-mcp"]

Gemini CLI

此仓库也是 Gemini CLI 扩展。使用以下命令安装：

gemini extensions install https://github.com/tidybytetools/pdf-table-pull-lite

工具：extract_pdf_tables(path, pages="", strategy="auto", output_dir="")。它会返回一个列表，其中包含每个表格的 CSV 文本。如果设置了 output_dir，它会将 CSV 保存到该目录，并改为返回文件路径。

在 GitHub Actions 中使用

每次工作流运行时，都可以从仓库中的 PDF 或工作流下载的 PDF 报告中提取表格。每个表格会生成一个 CSV，并在运行页面上显示预览。

name: PDF tables
on: [push, workflow_dispatch]
permissions:
  contents: read
jobs:
  tables:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tidybytetools/pdf-table-pull-lite@v1
        with:
          files: reports/**/*.pdf
          artifact-name: pdf-tables   # download the CSVs from the run page

每个 PDF 都会在 pdf-tables/ 中获得自己的 CSV 文件夹，文件夹名称根据 PDF 的路径生成。例如，reports/june.pdf 会生成 pdf-tables/reports/june/page1_table1.csv。

它会使用你选择的同一标签中的代码运行，并固定 pdfplumber 版本。无需 API 密钥或账户，PDF 也不会发送到 GitHub 以外的任何地方。它支持 Linux、Windows 和 Mac 运行器。扫描页面（仅有图片、没有文本）会被跳过，并发出警告。

输入

输入	默认值	作用
files	**/*.pdf	要读取的 PDF。Glob 模式，每行一个或用逗号分隔。
exclude	node_modules/**、**/node_modules/**、vendor/**	要跳过的模式。
output-dir	pdf-tables	CSV 文件的文件夹。
pages	（空）	要读取每个 PDF 中的页面，例如 1,3-5。留空则读取所有页面。
strategy	auto	lines（带边框的表格）、text（按空格对齐）或 auto（先尝试 lines，再尝试 text）。
fail-if-no-tables	false	PDF 中没有表格时失败。
fail-on-scanned	false	PDF 中有无文本的扫描页面时失败。
fail-if-no-files	true	没有匹配的文件时失败。
artifact-name	（空）	如果设置，则以此名称将 CSV 上传为构件。
python-version	（空）	要设置的 Python 版本。留空则使用运行器中的 Python（3.10 或更高版本）。

输出

输出	含义
files	已读取的 PDF 数量。
tables	已保存为 CSV 的表格数量。
scanned-files	包含扫描页面的 PDF 数量。
output-dir	CSV 文件所在的文件夹。

面向 AI Agent

• 适用场景： 你有一份包含真实文本（可以选中文字）的本地 PDF，并需要将其中的表格提取为行。
• 不适用场景： PDF 是扫描件或照片、有密码，或你需要 Excel。这些页面会被跳过。此类情况请使用付费版本。
• 输入： 文件路径，以及可选的 pages（例如 1,3-5）和 strategy（auto、lines、text）。
• 输出： CSV 字符串列表，每个表格对应一个字符串，首行为表头。空列表表示未找到表格。
• CLI 成功时退出代码为 0，出错时为 1（错误消息输出到 stderr）。另请参阅 llms.txt。

测试

pip install pdfplumber "mcp<2"
python3 -m unittest discover tests

许可证

MIT。详见 LICENSE。