pdf-table-pull-lite

io.github.tidybytetoolsPublished by GitHub account tidybytetoolsv1.2.1Updated Nov 5, 2026

Pull tables out of local text PDFs as CSV. Runs on your computer, nothing uploaded.

VerifiedSTDIODesktop onlyFiles & StorageData & Analytics

Overview

AI-generated overview

Local MCP server that extracts tables from text-based PDFs on your computer and returns them as CSV, one per table.

What you can do
  • Extract tables from a local text PDF, optionally limited to specific pages and with a chosen detection strategy (ruled lines, spacing, or automatic).
  • Return each detected table as CSV text with the first row as header, or save the CSVs to a chosen output directory and return the file paths.
  • Report which pages were skipped because they are scanned images without a text layer.
When to use it
Useful when an assistant needs the rows and columns of a table from a PDF already on the machine, for example to load them into a spreadsheet, pandas or a database. Not suitable for scanned PDFs, password-protected files, or when Excel or JSON output is required.
Requirements
Runs locally over stdio via uvx, so the uv toolchain must be installed; the package needs Python 3.10 or newer. No API key, account, environment variables or headers are required, and files are not uploaded.
Before you install
Only reads local files and writes CSV output where you point it, so review the output directory. Merged cells or unclear column layouts can put cells in the wrong place, and numbers are not cleaned, so check the CSVs before relying on them. Scanned pages are skipped silently apart from a notice. The README advertises a paid version for OCR, Excel output and cross-page joins.

Installation

In SourceWeft

  1. Open pdf-table-pull-lite in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[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

lite (free)pdf-table-pull
Text PDFs, ruled or spaced tablesyesyes
CSV outputyesyes
Excel (one sheet per table) and JSON outputnoyes
Scanned PDFs (OCR)noyes
Join tables across pagesnoyes
Numbers cleaned (1,200 → 1200, (40) → -40)noyes
Password-protected PDFsnoyes

How it compares to other free tools

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

pdf-table-pull-litepdfplumberCamelottabula-py
What it isCommand line toolPython libraryPython library + CLIPython wrapper for Tabula
Needs Javanononoyes
One command to get CSVsyesno, you write codeyesyes
Picks border or spacing mode for youyes (auto)nonoyes (guess)
Tells you which pages are scansyesnonono
Built-in MCP server for AI appsyesnonono
Lots of tuning knobsnoyesyessome

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:

json
{  "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):

json
{  "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:

json
{  "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:

json
{  "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:

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.

yaml
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

InputDefaultWhat it does
files**/*.pdfWhich PDFs to read. Glob patterns, one per line or split by commas.
excludenode_modules/**, **/node_modules/**, vendor/**Patterns to skip.
output-dirpdf-tablesFolder for the CSV files.
pages(empty)Pages to read in every PDF, like 1,3-5. Empty reads all pages.
strategyautolines (tables with borders), text (lined up by spaces), or auto (lines, then text).
fail-if-no-tablesfalseFail when a PDF has no tables.
fail-on-scannedfalseFail when a PDF has scanned pages with no text.
fail-if-no-filestrueFail 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

OutputWhat it is
filesHow many PDFs were read.
tablesHow many tables were saved as CSV.
scanned-filesHow many PDFs have scanned pages.
output-dirThe 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.

Source: README.md at commit 1d9db2f

Tools

1

extract_pdf_tables

Extract PDF tables to CSV

Pull the tables out of a local text PDF. Use this when you need the rows and columns of a table from a PDF on this computer, for example to load them into a spreadsheet, pandas or a database. Do not use it for scanned PDFs or photos (there is no OCR), for PDFs on the web (download the file first), or when you want the whole document as text (use a PDF-to-Markdown or text tool instead). path: full path to a PDF on this computer. pages: optional, like "1,3-5". Empty means all pages. strategy: "auto" (default, tries borders first, then spacing), "lines" (tables with ruled borders) or "text" (tables lined up by spacing). Try "text" if "auto" misses a table that has no border lines. output_dir: optional. If set, each table is saved there as a CSV and the file paths are returned. Files named pageN_tableM.csv that already exist there are replaced. If empty, nothing is written and the CSV text of each table is returned. Scanned (image-only) pages have no text and are skipped. Returns [] if no tables.

Parameterspathrequiredpagesstrategyoutput_dir

Version history

2
  1. v1.2.1LatestNov 4, 2026
  2. v1.1.0Nov 4, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts