pdf-table-pull-lite

[Tidy Byte Tools]

pdf-table-pull-lite

[License: MIT] [Python 3.10+] [MCP server] [MCP Registry] [PyPI downloads] [Glama score] [Action test]

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 5pdf-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 columnsSaved: statement_tables/page1_table1.csvSaved: 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

How it compares to other free tools

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

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 tableson: [push, workflow_dispatch]permissions:  contents: readjobs:  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

Outputs

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.