TableShot
The only MCP server for PDF table extraction. Give any AI assistant the ability to read tables from PDFs -- no other tool does this.
Camelot, Tabula, and Table Transformer are Python libraries -- they require a developer to write code. TableShot is an MCP server: Claude Desktop, Cursor, and Windsurf can use it directly with zero code.
~33MB install. No model downloads. No API keys. Results in <100ms.
The Problem
Ask any AI assistant to read a table from a PDF. It can't -- you get word soup:
Sales Report Q1 2024 Product Price Quantity Total Widget A $10.00 100
$1,000.00 Widget B $25.50 50 $1,275.00 Widget C $5.99 200 $1,198.00
TableShot gives you this:
| Product | Price | Quantity | Total |
|---|---|---|---|
| Widget A | $10.00 | 100 | $1,000.00 |
| Widget B | $25.50 | 50 | $1,275.00 |
| Widget C | $5.99 | 200 | $1,198.00 |
| Widget D | $149.00 | 10 | $1,490.00 |
Quick Start
Claude Desktop / Cursor / Windsurf
Add to your MCP config:
{
"mcpServers": {
"tableshot": {
"command": "uvx",
"args": ["tableshot"]
}
}
}
Then just ask: "Extract the tables from /path/to/report.pdf"
pip
pip install tableshot
Run as a standalone MCP server:
tableshot # stdio transport (for MCP clients)
python -m tableshot # same thing
Tools
| Tool | What it does |
|---|---|
extract_tables |
Extract all tables as Markdown, CSV, JSON, or HTML |
list_tables |
Quick scan -- preview tables before extracting |
extract_tables
source: str # File path or URL to a PDF (or image with [ml] extra)
pages: str = "all" # "all", "1", "1-3", "1,3,5"
format: str = "markdown" # "markdown", "csv", "json", "html"
list_tables
source: str # File path or URL to a PDF
pages: str = "all" # "all", "1", "1-3", "1,3,5"
Returns table count, dimensions, headers, and a preview row for each table found.
Examples
Financial report (bordered table)
Input: BlackRock-style quarterly earnings PDF
Output (markdown):
| | Q3 2023 | Q3 2022 | 9M 2023 | 9M 2022 |
| ------------------------------------ | ---------- | ---------- | ---------- | ---------- |
| Total revenue | $4,522 | $4,311 | $13,228 | $13,536 |
| Total expense | 2,885 | 2,785 | 8,538 | 8,578 |
| Operating income | $1,637 | $1,526 | $4,690 | $4,958 |
| Operating margin | 36.2% | 35.4% | 35.5% | 36.6% |
Extracted in 25ms.
Multi-table document
Input: PDF with employee directory + budget summary on the same page
Output: Both tables extracted separately with correct headers:
Table 1: 3 rows x 3 cols (Name, Department, Email)
Table 2: 4 rows x 2 cols (Category, Amount)
Wide table (8 columns, landscape)
| ID | Name | Q1 | Q2 | Q3 | Q4 | Total | Status |
| --- | ----- | --- | --- | --- | --- | ----- | ------ |
| 1 | Alpha | 100 | 150 | 200 | 250 | 700 | Active |
| 2 | Beta | 90 | 110 | 130 | 170 | 500 | Active |
| 3 | Gamma | 0 | 0 | 50 | 80 | 130 | New |
All 4 output formats (Markdown, CSV, JSON, HTML) available for every extraction.
Benchmarks
Tested on 10 PDFs covering bordered tables, multi-table pages, multi-page documents, special characters, wide tables, and real financial statements.
| Metric | Result |
|---|---|
| Bordered table accuracy | 8/8 exact match |
| Speed (bordered tables) | 4-25ms per extraction |
| Speed (3-page financial PDF) | 182ms |
| Output format validity | 36/36 pass (9 PDFs x 4 formats) |
Test Data
Generated fixtures — click Source to see the input PDF, Output to see what TableShot extracts:
| Fixture | Description | Source | Output | Speed |
|---|---|---|---|---|
| simple_bordered | 4-column sales report (Product, Price, Quantity, Total) | Extracted | 10ms | |
| multi_table | Two tables on one page: employee directory + budget summary | Extracted | 10ms | |
| single_row | Minimal table — header + one data row | Extracted | 4ms | |
| multi_page | One table per page across 2 pages | Extracted | 9ms | |
| empty_page | Page 1 text only; page 2 has a table | Extracted | 6ms | |
| special_chars | Cells with $, :, ", &, <> |
Extracted | 6ms | |
| wide_table | 8-column landscape table (Q1–Q4, Total, Status) | Extracted | 11ms |
Real-world PDFs (not included in repo due to size/licensing):
| Description | Tables | Speed | |
|---|---|---|---|
| BlackRock mock | Generated mock of a BlackRock quarterly earnings statement (5 columns) | 1 table, 11 rows | 25ms |
| Sample Financial Statements | 3-page financial statement with complex visual formatting (155KB) | 3 tables, 75 rows | 182ms |
| NHM table | Large 56-page document with 55 tables (25MB) | 55 tables, 2321 rows | 5.8s |
Full machine-readable results in benchmarks/results.json. Detailed before/after comparisons in benchmarks/results.md.
vs Other Tools
| TableShot | Camelot | Tabula-py | Table Transformer | |
|---|---|---|---|---|
| Install | ~33MB, nothing else | Needs Ghostscript | Needs Java (100-300MB) | Needs PyTorch (700MB-5GB) |
| Speed | ~10ms/table | >20s worst case | Variable (JVM startup) | 2-5s/page |
| Bordered tables | Excellent | Excellent | Good | Excellent |
| Borderless | Good (text fallback) | Poor | Better detection | Best |
| MCP support | Native | None | None | None |
| Maintained | Active | ~5 years stale | Active | Active |
Competitor data from Adhikari & Agarwal 2024, OpenNews 2024 review, and published GitHub metrics. Full results in benchmarks/results.md.
Need Scanned PDFs or Images?
The base install handles native PDFs with text layers (90%+ of real-world use cases). For scanned documents and images:
pip install tableshot[ml] # Table Transformer for image-based tables
pip install tableshot[ocr] # OCR for scanned documents (ONNX, no PyTorch)
pip install tableshot[all] # Everything
With [ml] installed, TableShot automatically detects whether a PDF has a text layer:
- Text layer present -- uses pdfplumber (fast, ~10ms)
- Scanned / no text layer -- uses Table Transformer for detection, pdfplumber for text extraction
- Image files (PNG, JPEG) -- uses Table Transformer + OCR (requires
[ocr])
You can also force the ML backend: extract_tables("/path/to/scan.pdf", backend="ml")
How It Works
PDF/Image ──> Smart Router ──> Table Detection ──> Cell Extraction ──> Formatted Output
| |
| PDF with text layer: | Markdown
| pdfplumber (lines → text fallback) | CSV
| | JSON
| Scanned PDF / Image (with [ml]): | HTML
| Table Transformer → pdfplumber text / OCR |
- pdfplumber handles PDF parsing and table detection (MIT)
- pypdfium2 renders PDF pages to images for ML backend (Apache-2.0)
- Table Transformer (optional
[ml]) detects tables in images (MIT) - MCP SDK exposes tools to AI assistants via stdio transport (MIT)
Total base install: ~33MB. No model downloads. No GPU required.
Known Limitations
All rule-based PDF table extractors (including Camelot and Tabula) share these limits:
- Financial statements with visual formatting -- amounts positioned by whitespace rather than cell borders can fragment across columns
- Scanned PDFs / images -- no OCR in base install (use
tableshot[ml]ortableshot[ocr]) - Scientific papers with equations -- inline math breaks table boundary detection
- Complex borderless tables -- ambiguous column alignment can cause misdetection
We're honest about these. For edge cases, tableshot[ml] adds Table Transformer support.
Contributing
git clone https://github.com/Bespoke34/tableshot.git
cd tableshot
pip install -e ".[dev]"
pip install fpdf2 # for generating test fixtures
python tests/generate_fixtures.py # create test PDFs
pytest -m "not slow" # run 160 tests (skip ML tests)
pytest # run all 167 tests (needs [ml] extra)
ruff check src/ tests/ # lint
- 95% test coverage, all tests must pass
- Ruff clean, no lint warnings
- MIT license -- all dependencies must be MIT/Apache-2.0/BSD compatible
License
MIT
Metadata
Release files for tableshot 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tableshot-0.1.1.tar.gz | 49.2 kB | With provenance | Details for tableshot-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tableshot-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for tableshot-0.1.1-py3-none-any.whl |
Total release size: 70.0 kB
Release files / tableshot-0.1.1.tar.gz
| Download URL | tableshot-0.1.1.tar.gz |
|---|---|
| Size | 49.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
470fb5c07d4688f76bf751d81b0384689dfb558552b18b98292566d714660501
|
|
BLAKE2b-256 checksum How to use checksums |
f1cf00c30e8fa01c8426b93320c49e4511d4c70bc97fd7224471d29e327cfe2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 13, 2026.
Transparency logRelease files / tableshot-0.1.1-py3-none-any.whl
| Download URL | tableshot-0.1.1-py3-none-any.whl |
|---|---|
| Size | 20.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55067fe66e403e3fb5fb63c2aa18c3bfc5cdf08670cc90eb6471dc459973e812
|
|
BLAKE2b-256 checksum How to use checksums |
9ebb1be2c94dd9fd4590f3d5e46b3561b9a03aeaf51c4bee30bd1ff877ff3374
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 13, 2026.
Transparency logSecurity for tableshot 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tableshot-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.