{"id":"c93420c6-dcfe-4b8d-95c5-7c7c27a97071","slug":"pdf-table-pull-lite","kind":"mcp","name":"pdf-table-pull-lite","summary":"Pull tables out of text PDFs into CSV. Free lite version of pdf-table-pull.","owner":"tidybytetools","repoUrl":"https://github.com/tidybytetools/pdf-table-pull-lite","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-11-04T07:57:29.000Z","addedAt":"2026-11-08T04:33:43.917Z","logoUrl":"https://avatars.githubusercontent.com/u/352319590?u=02712f6e0c7c0d7a2335a0f0aa670f14b00c80ee&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","cloud-infra","data-analytics"],"tags":["cli","csv","data-extraction","pdf","pdf-tables","python","table-extraction","gemini-cli-extension"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-08T04:34:47.713Z","sample":false,"url":"https://conduits.dev/tools/pdf-table-pull-lite","language":"Python","transports":["stdio"],"install":{"pypi":"pdf-table-pull-lite"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p>\n  <a href=\"https://github.com/tidybytetools\">\n    <picture>\n      <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/tidybytetools/pdf-table-pull-lite/main/assets/tidybytetools-lockup-dark.png\">\n      <img alt=\"Tidy Byte Tools\" src=\"https://raw.githubusercontent.com/tidybytetools/pdf-table-pull-lite/main/assets/tidybytetools-lockup-light.png\" height=\"44\">\n    </picture>\n  </a>\n</p>\n\n# pdf-table-pull-lite\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/tidybytetools/pdf-table-pull-lite/blob/main/LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)\n[![MCP server](https://img.shields.io/badge/MCP-stdio-purple.svg)](#use-it-with-your-ai-app-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-green.svg)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.tidybytetools/pdf-table-pull-lite)\n[![PyPI downloads](https://img.shields.io/pypi/dm/pdf-table-pull-lite.svg)](https://pypistats.org/packages/pdf-table-pull-lite)\n[![Glama score](https://glama.ai/mcp/servers/tidybytetools/pdf-table-pull-lite/badges/score.svg)](https://glama.ai/mcp/servers/tidybytetools/pdf-table-pull-lite)\n[![Action test](https://github.com/tidybytetools/pdf-table-pull-lite/actions/workflows/action-test.yml/badge.svg)](https://github.com/tidybytetools/pdf-table-pull-lite/actions/workflows/action-test.yml)\n\n**Free. No API key. Runs on your own computer, so your PDFs stay with you.**\n\nA tool that pulls the tables out of a text PDF and saves each one as a CSV file.\nNeed Excel output, scanned PDFs or tables joined across pages? The paid version does that: **[pdf-table-pull on Gumroad](https://tidybyte.gumroad.com/l/hkxqxh)**\n\nRuns on your own computer, so your PDFs are never uploaded anywhere. MIT license. Python 3.10 or newer, on Windows, Mac and Linux.\n\nAlso searched as: ES: extraer tablas de PDF, PDF a CSV / PT: extrair tabelas de PDF / DE: PDF-Tabellen extrahieren / FR: extraire des tableaux PDF / JA: PDFテーブル抽出、PDFをCSVに\n\n## Links\n\n- **[Website](https://tidybytetools.github.io/tools/pdf-table-pull/)** — product page with prices and options\n- **[Apify (no-install cloud version)](https://apify.com/tidybytetools/pdf-table-pull)** — pay only for what you use\n- **[Pro version on Gumroad](https://tidybyte.gumroad.com/l/hkxqxh)** — Excel output, scanned PDFs, tables joined across pages\n\n<!-- mcp-name: io.github.tidybytetools/pdf-table-pull-lite -->\n\n## Before and after\n\nBefore: a text PDF (you can highlight the words) with a table. After: one CSV file per table. Scanned, image-only pages are skipped and listed. This free tool does not write Excel and does not do OCR.\n\n## Install\n\n```\npip install pdf-table-pull-lite\n```\n\nOr use pipx, which keeps it in its own space:\n\n```\npipx install pdf-table-pull-lite\n```\n\nWant the newest code from GitHub instead?\n\n```\npip install git+https://github.com/tidybytetools/pdf-table-pull-lite\n```\n\n## Use it\n\n```\npdf-table-pull-lite statement.pdf                 # CSVs go in statement_tables/\npdf-table-pull-lite statement.pdf -o out/ -p 2-5  # only pages 2 to 5\npdf-table-pull-lite statement.pdf -s text         # tables with no border lines\n```\n\nExample run:\n\n```\nFound 2 table(s).\n  page1_table1: 2 rows x 3 columns\n  page1_table2: 2 rows x 2 columns\nSaved: statement_tables/page1_table1.csv\nSaved: statement_tables/page1_table2.csv\n```\n\nYou 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).\n\n`--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.\n\nWhen 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.\n\n## Known limits\n\n- **Scanned PDFs.** Pages that are just an image (no text layer) are skipped, and the tool tells you which ones.\n- **Tables that continue onto the next page** come out as separate CSVs, one per page.\n- **Odd layouts.** Tables with merged cells or no clear columns can come out with cells in the wrong spot. Check the CSV.\n- **CSV only.** No Excel or JSON output, no number cleanup (so `(40)` stays as text), and no password-protected PDFs.\n\n## Lite vs paid\n\n| | lite (free) | [pdf-table-pull](https://tidybyte.gumroad.com/l/hkxqxh) |\n|---|---|---|\n| Text PDFs, ruled or spaced tables | yes | yes |\n| CSV output | yes | yes |\n| Excel (one sheet per table) and JSON output | no | yes |\n| Scanned PDFs (OCR) | no | yes |\n| Join tables across pages | no | yes |\n| Numbers cleaned (`1,200` → 1200, `(40)` → -40) | no | yes |\n| Password-protected PDFs | no | yes |\n\n## How it compares to other free tools\n\nAll of these are free and open source. Pick what fits you.\n\n| | pdf-table-pull-lite | [pdfplumber](https://github.com/jsvine/pdfplumber) | [Camelot](https://github.com/camelot-dev/camelot) | [tabula-py](https://github.com/chezou/tabula-py) |\n|---|---|---|---|---|\n| What it is | Command line tool | Python library | Python library + CLI | Python wrapper for Tabula |\n| Needs Java | no | no | no | yes |\n| One command to get CSVs | yes | no, you write code | yes | yes |\n| Picks border or spacing mode for you | yes (`auto`) | no | no | yes (guess) |\n| Tells you which pages are scans | yes | no | no | no |\n| Built-in MCP server for AI apps | yes | no | no | no |\n| Lots of tuning knobs | no | yes | yes | some |\n\nThis tool is built on pdfplumber. If you want full control in your own code, use pdfplumber or Camelot directly.\n\n## Use it with your AI app (MCP)\n\nThere 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](https://docs.astral.sh/uv/), which gives you the `uvx` command.\n\nRun it by hand to check it starts (it waits quietly for an app to talk to it):\n\n```\nuvx --from pdf-table-pull-lite pdf-table-pull-lite-mcp\n```\n\nShorter way to start the same server: `uvx pdf-table-pull-lite mcp`.\n\nPick your app below and copy the block. Restart the app after you save.\n\n### Claude Desktop\n\nOpen **Settings > Developer > Edit Config**. That opens `claude_desktop_config.json`. Add this:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-table-pull-lite\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"pdf-table-pull-lite\", \"pdf-table-pull-lite-mcp\"]\n    }\n  }\n}\n```\n\nIf Claude says it can't find `uvx`, run `which uvx` (Mac/Linux) or `where uvx` (Windows) and put that full path in `\"command\"`.\n\n### Cursor\n\nPut the same block in `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-table-pull-lite\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"pdf-table-pull-lite\", \"pdf-table-pull-lite-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nVS Code uses `servers`, not `mcpServers`. Put this in `.vscode/mcp.json` in your project, or run **MCP: Open User Configuration** to use it everywhere:\n\n```json\n{\n  \"servers\": {\n    \"pdf-table-pull-lite\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"pdf-table-pull-lite\", \"pdf-table-pull-lite-mcp\"]\n    }\n  }\n}\n```\n\nOr add it with one command:\n\n```\ncode --add-mcp '{\"name\":\"pdf-table-pull-lite\",\"type\":\"stdio\",\"command\":\"uvx\",\"args\":[\"--from\",\"pdf-table-pull-lite\",\"pdf-table-pull-lite-mcp\"]}'\n```\n\n### Cline\n\nIn the Cline panel, click the **MCP Servers** icon, open **Configure**, then click **Configure MCP Servers**. Add this inside `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-table-pull-lite\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"pdf-table-pull-lite\", \"pdf-table-pull-lite-mcp\"],\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n### Codex\n\nOne command:\n\n```\ncodex mcp add pdf-table-pull-lite -- uvx --from pdf-table-pull-lite pdf-table-pull-lite-mcp\n```\n\nOr add this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.pdf-table-pull-lite]\ncommand = \"uvx\"\nargs = [\"--from\", \"pdf-table-pull-lite\", \"pdf-table-pull-lite-mcp\"]\n```\n\n### Gemini CLI\n\nThis repo is also a Gemini CLI extension. Install it with:\n\n```\ngemini extensions install https://github.com/tidybytetools/pdf-table-pull-lite\n```\n\nTool: `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.\n\n## Use it in GitHub Actions\n\nPull 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.\n\n```yaml\nname: PDF tables\non: [push, workflow_dispatch]\npermissions:\n  contents: read\njobs:\n  tables:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: tidybytetools/pdf-table-pull-lite@v1\n        with:\n          files: reports/**/*.pdf\n          artifact-name: pdf-tables   # download the CSVs from the run page\n```\n\nEach 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`.\n\nIt 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.\n\n### Inputs\n\n| Input | Default | What it does |\n|---|---|---|\n| `files` | `**/*.pdf` | Which PDFs to read. Glob patterns, one per line or split by commas. |\n| `exclude` | `node_modules/**`, `**/node_modules/**`, `vendor/**` | Patterns to skip. |\n| `output-dir` | `pdf-tables` | Folder for the CSV files. |\n| `pages` | (empty) | Pages to read in every PDF, like `1,3-5`. Empty reads all pages. |\n| `strategy` | `auto` | `lines` (tables with borders), `text` (lined up by spaces), or `auto` (lines, then text). |\n| `fail-if-no-tables` | `false` | Fail when a PDF has no tables. |\n| `fail-on-scanned` | `false` | Fail when a PDF has scanned pages with no text. |\n| `fail-if-no-files` | `true` | Fail when no files match. |\n| `artifact-name` | (empty) | If set, upload the CSVs as an artifact with this name. Hidden folders like `.github/` are included. |\n| `python-version` | (empty) | Python to set up. Empty uses the runner's Python (3.10 or newer). |\n\n### Outputs\n\n| Output | What it is |\n|---|---|\n| `files` | How many PDFs were read. |\n| `tables` | How many tables were saved as CSV. |\n| `scanned-files` | How many PDFs have scanned pages. |\n| `output-dir` | The folder with the CSV files. |\n\n## For AI agents\n\n- **Use when:** you have a local PDF with real text (you can select the words) and need its tables as rows.\n- **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.\n- **Input:** a file path, plus optional `pages` like `1,3-5` and `strategy` (`auto`, `lines`, `text`).\n- **Output:** a list of CSV strings, one per table, first row is the header. Empty list means no tables were found.\n- CLI exit code is 0 on success and 1 on error (message on stderr). See also [`llms.txt`](https://github.com/tidybytetools/pdf-table-pull-lite/blob/main/llms.txt).\n\n## Tests\n\n```\npip install pdfplumber \"mcp<2\"\npython3 -m unittest discover tests\n```\n\n## FAQ\n\n**What PDFs work?**\nText PDFs where you can select the words. Scanned (picture-only) pages are skipped.\n\n**Do my PDFs leave my computer?**\nNo. The tool runs on your computer. Nothing is uploaded.\n\n**How is this different from the Pro version?**\nPro adds Excel and JSON output, OCR for scans, and tables joined across pages.\n\n**Does it work with AI apps?**\nYes. It includes a free MCP server. No API key.\n## License\n\nMIT. See `LICENSE`.\n"}