pdf-table-pull-lite

pdf-table-pull-lite

Free. No API key. Runs on your own computer, so your PDFs stay with you.

A tool that pulls the tables out of a text PDF and saves each one as a CSV file. Need Excel output, scanned PDFs or tables joined across pages? The paid version does that: pdf-table-pull on Gumroad

Runs on your own computer, so your PDFs are never uploaded anywhere. MIT license. Python 3.10 or newer, on Windows, Mac and Linux.

Install

pip install pdf-table-pull-lite

Or use pipx, which keeps it in its own space:

pipx install pdf-table-pull-lite

Want the newest code from GitHub instead?

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

Use it

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

Example run:

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

You get one CSV per table, named after its page. The CSVs open straight in Excel (they're saved as UTF-8 with a BOM so accents show correctly).

--strategy (-s): lines is for tables with ruled borders, text is for tables lined up by spacing, and auto (the default) tries lines first, then text.

When you run it in a terminal it ends with one short line about the paid version. --quiet turns it off, and it never shows when output is piped or redirected.

Known limits

• Scanned PDFs. Pages that are just an image (no text layer) are skipped, and the tool tells you which ones.
• Tables that continue onto the next page come out as separate CSVs, one per page.
• Odd layouts. Tables with merged cells or no clear columns can come out with cells in the wrong spot. Check the CSV.
• CSV only. No Excel or JSON output, no number cleanup (so (40) stays as text), and no password-protected PDFs.

Lite vs paid

	lite (free)	pdf-table-pull
Text PDFs, ruled or spaced tables	yes	yes
CSV output	yes	yes
Excel (one sheet per table) and JSON output	no	yes
Scanned PDFs (OCR)	no	yes
Join tables across pages	no	yes
Numbers cleaned (1,200 → 1200, (40) → -40)	no	yes
Password-protected PDFs	no	yes

How it compares to other free tools

All of these are free and open source. Pick what fits you.

	pdf-table-pull-lite	pdfplumber	Camelot	tabula-py
What it is	Command line tool	Python library	Python library + CLI	Python wrapper for Tabula
Needs Java	no	no	no	yes
One command to get CSVs	yes	no, you write code	yes	yes
Picks border or spacing mode for you	yes (auto)	no	no	yes (guess)
Tells you which pages are scans	yes	no	no	no
Built-in MCP server for AI apps	yes	no	no	no
Lots of tuning knobs	no	yes	yes	some

This tool is built on pdfplumber. If you want full control in your own code, use pdfplumber or Camelot directly.

Use it with your AI app (MCP)

There is a small free MCP server built in. It gives your AI app one tool, extract_pdf_tables. No API key or account is needed. It needs uv, which gives you the uvx command.

Run it by hand to check it starts (it waits quietly for an app to talk to it):

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

Shorter way to start the same server: uvx pdf-table-pull-lite mcp.

Pick your app below and copy the block. Restart the app after you save.

Claude Desktop

Open Settings > Developer > Edit Config. That opens claude_desktop_config.json. Add this:

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

If Claude says it can't find uvx, run which uvx (Mac/Linux) or where uvx (Windows) and put that full path in "command".

Cursor

Put the same block in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

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

VS Code

VS Code uses servers, not mcpServers. Put this in .vscode/mcp.json in your project, or run MCP: Open User Configuration to use it everywhere:

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

Or add it with one command:

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

Cline

In the Cline panel, click the MCP Servers icon, open Configure, then click Configure MCP Servers. Add this inside mcpServers:

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

Codex

One command:

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

Or add this to ~/.codex/config.toml:

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

Gemini CLI

This repo is also a Gemini CLI extension. Install it with:

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

Tool: extract_pdf_tables(path, pages="", strategy="auto", output_dir=""). It returns a list with the CSV text of each table. If you set output_dir, it saves the CSVs there and returns the file paths instead.

Use it in GitHub Actions

Pull the tables out of PDFs in your repo, or out of a PDF report your workflow downloads, every time it runs. You get one CSV per table and a preview on the run page.

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

Each PDF gets its own folder of CSVs inside pdf-tables/, named after the PDF's path. For example reports/june.pdf gives pdf-tables/reports/june/page1_table1.csv.

It runs the code in the same tag you pick, with a fixed pdfplumber version. No API key, no account, and your PDFs are not sent anywhere outside GitHub. It works on Linux, Windows and Mac runners. Scanned pages (just a picture, no text) are skipped with a warning.

Inputs

Input	Default	What it does
files	**/*.pdf	Which PDFs to read. Glob patterns, one per line or split by commas.
exclude	node_modules/**, **/node_modules/**, vendor/**	Patterns to skip.
output-dir	pdf-tables	Folder for the CSV files.
pages	(empty)	Pages to read in every PDF, like 1,3-5. Empty reads all pages.
strategy	auto	lines (tables with borders), text (lined up by spaces), or auto (lines, then text).
fail-if-no-tables	false	Fail when a PDF has no tables.
fail-on-scanned	false	Fail when a PDF has scanned pages with no text.
fail-if-no-files	true	Fail when no files match.
artifact-name	(empty)	If set, upload the CSVs as an artifact with this name.
python-version	(empty)	Python to set up. Empty uses the runner's Python (3.10 or newer).

Outputs

Output	What it is
files	How many PDFs were read.
tables	How many tables were saved as CSV.
scanned-files	How many PDFs have scanned pages.
output-dir	The folder with the CSV files.

For AI agents

• Use when: you have a local PDF with real text (you can select the words) and need its tables as rows.
• Don't use when: the PDF is a scan or photo, it has a password, or you need Excel. Those pages get skipped. Use the paid version for those.
• Input: a file path, plus optional pages like 1,3-5 and strategy (auto, lines, text).
• Output: a list of CSV strings, one per table, first row is the header. Empty list means no tables were found.
• CLI exit code is 0 on success and 1 on error (message on stderr). See also llms.txt.

Tests

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

License

MIT. See LICENSE.