pdf-slice-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
pdf-slice
PDF → clean markdown that never silently returns wrong content.
A small, local, CPU-only tool that converts a PDF (file or URL) to clean markdown — and is engineered around one rule: if the output might be wrong or incomplete, it says so, loudly. No silent failures, no wrong documents, no empty results dressed up as success.
Why this exists
pdf-slice is built directly from two real, silent failure modes reported against Firecrawl's PDF pipeline:
Cache served the wrong document — several different files that shared the name
Nexus.pdfcollided in the cache, so a user asking for the April report silently received the March report, with a200status and correct-looking metadata. pdf-slice keys its cache by full URL + SHA-256 of the downloaded bytes — never the filename — and re-verifies the content hash before serving anything from cache. A mismatch means a fresh extraction, never the wrong document.White text hidden in nested forms — a 46-page PDF whose body text was white, nested inside form XObjects under an opaque image, came back as ~3,000 header-only characters while other extractors found 86,000+. The classifier had declared "text-based, confidence 1.0, no OCR needed". pdf-slice treats a suspiciously thin native extraction as a signal, not an answer: it falls back to OCR automatically and always reports which path produced the output.
Related MCP server: document-parser
What you get
Clean markdown with natural reading order (multi-column aware) and tables preserved as markdown tables. A table that is detected but cannot be parsed reliably produces a warning — never silent loss.
Provenance metadata (JSON) for every run:
extraction_path(native/ocr/fallback), per-page origin, character counts, table counts and timings,content_hash, cache state (hit/miss/miss-hash-mismatch), andwarnings.RAG chunks (JSONL) with provenance: each chunk carries
text,page,element_type(heading/paragraph/table),confidence,source(URI + content hash) andreading_order.Batch mode: process a whole folder of PDFs with one command and get a summary report (files, OCR pages, warnings).
Loud failures: encrypted, corrupt, empty, zero-byte and non-PDF inputs fail with a clear error — never with empty "successful" output.
MCP server for Claude Code, Cursor and Codex, plus a ready-made agent skill (
skills/pdf-slice/SKILL.md).
Install
# from source
git clone https://github.com/kamalmosadegh/pdf-slice && cd pdf-slice
python -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python extract.py --help
# or as a package (console entry points)
pip install .
pdf-slice --help
# one command, after PyPI release
uvx pdf-slice --helpDependencies are light and CPU-only: PyMuPDF, pytesseract, Pillow and the MCP SDK. No GPU models, no API key, no paid service.
OCR uses the system tesseract binary (eng and fas supported). If it
is missing, the tool continues with a loud warning and returns
low-confidence output for scanned pages — never silence:
sudo apt-get install -y tesseract-ocr tesseract-ocr-fasUsage
# one file -> markdown + JSON metadata
pdf-slice report.pdf
# a URL (cache key = full URL + content hash)
pdf-slice https://example.com/api/docs/123
# RAG chunks with provenance (JSONL, one object per line)
pdf-slice report.pdf --format jsonl
# markdown and chunks together
pdf-slice report.pdf --format both
# a whole folder + summary report
pdf-slice --batch ./pdfs --out-dir ./out
# Persian OCR
pdf-slice scanned-fa.pdf --ocr-lang eng+fas
# thresholds (defaults: 50 chars/page; 200 for pages with images)
pdf-slice scan.pdf --min-chars-per-page 80 --image-page-chars 300Golden rule: if warnings is non-empty, read them before trusting
the markdown. The fallback path means low confidence even after OCR.
Cache
URL key:
SHA-256(full URL); cached content is served only when the storedcontent_hashequals the hash of the freshly downloaded bytes.Local file key:
SHA-256of the file's bytes.Default location:
~/.cache/pdf-slice(override with--cache-diror thePDF_SLICE_CACHE_DIRenvironment variable).--no-cachedisables it entirely.
MCP server & agent skill
pdf-slice-mcp # stdio transport, for Claude Code / Cursor / Codexextract_pdf(source, ocr_lang="eng")— markdown + metadata + warnings.verify_pdf(source, second_source)— extracts the same document from two routes and reports amatch_rate; a low rate is a loud signal that one route served different content.Ready-made client configs:
mcp-config-claude.json,mcp-config-cursor.json(adjust the absolute paths to your machine).
Benchmark
Measured on the fixtures bundled in tests/fixtures/, generated by
tests/benchmark.py. "Silent error" = wrong or incomplete content
returned with no warning. The target is zero.
File | Path | Word recovery | Seconds/page | Silent errors |
white | native | 100% | 1.575 | 0 |
black | native | — | 1.480 | 0 |
scanned | ocr | 100% | 2.802 | 0 |
multilingual | native | 100% | 1.401 | 0 |
table | native | 100% | 1.632 | 0 |
columns | native | — | 1.452 | 0 |
large (120 pages) | native | — | 0.462 | 0 |
Total silent errors: 0.
Run the full pre-delivery test matrix (26 test groups × 3 repeats — cache collisions, white text, scanned, multilingual, tables, columns, large, corrupt, encrypted, batch, MCP, clean-install and more):
python tests/test_slice.pyDeliberately out of scope
A Firecrawl clone, crawling, anti-bot infrastructure, browser rendering, pricing, SDKs — and heavy layout/formula models (UniMERNet, TableFormer and friends). pdf-slice's edge is the never silently wrong guarantee and a fast native path, not heavyweight modelling.
License
MIT — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Turn URLs, PDFs and DOCX into clean Markdown for agents, plus prompt-injection scanning
Convert PDF, DOCX, PPTX, XLSX and HTML links to clean Markdown with tables and RAG chunks.
Any URL to clean markdown/JSON; PDF, XLSX, CSV, DOCX to text and tables. Free tier for agents.
Converts PDF, scans, DOCX, XLSX and PPTX to Markdown with tables and page-aware RAG chunks.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables AI agents to generate PDFs from Markdown or URLs, extract text, merge documents, and perform text conversions via the Model Context Protocol.81MIT
- AlicenseNot gradedqualityCmaintenanceProvides AI agents with comprehensive document parsing capabilities including PDF text extraction, OCR, HTML-to-markdown conversion, table extraction, and summarization, optimized for agent workflows.75 npmMIT
- AlicenseAqualityBmaintenanceConvert PDF, DOCX, HTML, and URLs into clean, LLM-ready markdown with tables preserved and boilerplate stripped, through three MCP tools (URL, local file, or raw bytes). Hosted API with no local dependencies; 50 free conversions with a self-serve key, then $0.002 per call.343 npmMIT
- AlicenseAqualityBmaintenanceTurns any URL into clean markdown/JSON and converts PDF, XLSX, CSV, DOCX into text and tables. Free tier of 100 calls/day, then pay-per-call credits.2MIT