[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_130":131},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91},"apiUrl","https://odel.app/api","creator","jztan","moduleId","pdf-mcp","@jztan/pdf-mcp","displayName","pdf mcp","tagline","Production-ready MCP server for PDF processing with intelligent caching.","iconKey","https://avatars.githubusercontent.com/u/6021013?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783340310000,"updatedAt",1788583208000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.jztan%2Fpdf-mcp","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",130,"upstreamUpdatedAt",1788582913000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/jztan/pdf-mcp","githubRepoFullName","jztan/pdf-mcp","releaseId","ext-jztan-pdf-mcp","version","3.1.0","descriptionMarkdown","# pdf-mcp\n\n[![PyPI version](https://img.shields.io/pypi/v/pdf-mcp)](https://pypi.org/project/pdf-mcp/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub Issues](https://img.shields.io/github/issues/jztan/pdf-mcp)](https://github.com/jztan/pdf-mcp/issues)\n[![CI](https://github.com/jztan/pdf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jztan/pdf-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/jztan/pdf-mcp/graph/badge.svg)](https://codecov.io/gh/jztan/pdf-mcp)\n[![Downloads](https://pepy.tech/badge/pdf-mcp)](https://pepy.tech/project/pdf-mcp)\n\n**Surgical PDF access for AI agents: search, read, and extract without flooding context.**\n\nAn [MCP](https://modelcontextprotocol.io/) server that lets Claude Code and other AI agents search a PDF by meaning or keyword, read only the pages that matter, and cleanly pull out tables, images, and scanned text, even from multi-column and Japanese layouts.\n\n**mcp-name: io.github.jztan/pdf-mcp**\n\n## Try it in your browser\n\n**[See what your AI agent sees →](https://pdf-mcp.jztan.com/)**\n\nDrop in any PDF, or a whole folder of them, and watch an agent triage the corpus, search across every document at once, and read only the pages that matter, using a fraction of the tokens. 100% client-side, no install required.\n\n

\n $\"pdf-mcp$ \n

\n\n## Why pdf-mcp?\n\n| | Without pdf-mcp | With pdf-mcp |\n|---|---|---|\n| Large PDFs | Context overflow | Read only the pages you need |\n| Finding content | Load everything | Hybrid search: BM25 keyword + semantic |\n| Folders of PDFs | One document at a time | Warm, triage, and search a whole folder |\n| Tables and charts | Lost in raw text | Structured rows, and `(x, y)` data from vector charts |\n| Multi-column and vertical layouts | Columns interleaved | Correct reading order, including Japanese tategaki |\n| Scanned PDFs | No text at all | OCR via Tesseract, parallel across pages |\n| Repeated access | Re-parse every time | SQLite cache that survives restarts |\n| Hidden or injected text | Silently ingested | Flagged as untrusted, nothing stripped |\n\n## Installation\n\n```bash\npip install pdf-mcp\n```\n\nThat is the whole install: hybrid search, corpus tools, multi-column and\nCJK reading order all work out of the box.\n\nOCR on scanned PDFs additionally needs system Tesseract:\n\n```bash\nbrew install tesseract # macOS\napt install tesseract-ocr # Ubuntu/Debian\nwinget install Tesseract-OCR # Windows\n```\n\n## Quick Start\n\n```bash\nclaude mcp add pdf-mcp -- pdf-mcp\n```\n\nThen ask Claude to read a PDF. For Claude Desktop, VS Code, Codex CLI,\nKiro, or any other MCP client, see **[docs/clients.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/clients.md)**.\n\nWhy this exists, and what broke along the way: [Claude's 100-page PDF limit and how I got around it](https://blog.jztan.com/how-i-built-pdf-mcp-solving-claude-large-pdf-limitations/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=quickstart-how-i-built-pdf-mcp-solving-claude-large-pdf-limitations)\n\n## Tools\n\n13 specialized tools rather than one monolithic one. Typical pattern:\n`pdf_info` to plan, `pdf_search` to locate (its paragraph excerpts often\nanswer the question outright), `pdf_read_pages` when you need more. For a\nfolder, `pdf_corpus_overview` to triage, then `pdf_corpus_search`.\n\n| Tool | What it does |\n|------|--------------|\n| `pdf_info` | Page count, metadata, TOC summary, scanned-page detection. **Call first.** |\n| `pdf_search` | Hybrid search (keyword + semantic), page or section granularity, paragraph or context-window excerpts with source coordinates |\n| `pdf_read_pages` | Read specific pages or ranges, with OCR on demand, tables, and embedded images |\n| `pdf_read_all` | Read a whole document in one call, byte-capped |\n| `pdf_get_toc` | Full table of contents for documents with many bookmarks |\n| `pdf_render_pages` | Render pages as PNG for vision models: diagrams, handwriting, scans |\n| `pdf_extract_chart` | Chart data as exact `(x, y)` tables, read from plot geometry |\n| `pdf_corpus_warm` | Warm a folder of PDFs into the cache within a time budget |\n| `pdf_corpus_overview` | Per-document triage cards for a folder |\n| `pdf_corpus_search` | Search across a folder, with document and page provenance; `excerpt_style=\"auto\"` picks the excerpt unit per query |\n| `pdf_cache_stats` | Per-document cache breakdown and total size |\n| `pdf_cache_clear` | Clear expired or all cache entries |\n| `server_info` | Which optional features and config are active |\n\nText returned by any of these is untrusted content extracted from a PDF.\n`pdf_info(content_trust=True)` reports hidden text a human reader cannot\nsee, and the read tools flag it per page.\n\nExample prompts:\n\n```\n\"Read the PDF at /path/to/document.pdf\"\n\"Which pages discuss supply chain risks?\"\n\"Find sections about the training process\"\n\"Show me what page 5 looks like\"\n\"OCR pages 3-5 of the scanned PDF\"\n```\n\nFull reference, every parameter and response shape:\n**[docs/tool-reference.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/tool-reference.md)**. Embedding model\nselection: **[docs/embedding-models.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/embedding-models.md)**.\n\n## Example Workflow\n\nFor a large document (e.g., a 200-page annual report):\n\n```\nUser: \"Summarize the risk factors in this annual report\"\n\nAgent workflow:\n1. pdf_info(\"report.pdf\")\n → 200 pages, TOC shows \"Risk Factors\" on page 89\n\n2. pdf_search(\"report.pdf\", \"risk factors\")\n → Matches with structural paragraph excerpts: each excerpt\n is the bullet, paragraph, or heading that matched, not a\n fixed-width window. Often enough to answer directly.\n\n3. If excerpts are sufficient → synthesize answer\n\n4. If more context needed:\n pdf_read_pages(\"report.pdf\", \"89-95\")\n → Full page text for deeper reading\n```\n\n## Remote / HTTP transport\n\nSTDIO is the default and is what every example above uses. `pdf-mcp-http`\nserves the same tools over HTTP, for clients that cannot spawn a process\n(the Anthropic API MCP connector, claude.ai custom connectors) and for a\nwarm corpus shared by several clients.\n\n```bash\nexport PDF_MCP_AUTH_TOKEN=\"$(openssl rand -hex 32)\"\npdf-mcp-http\n```\n\nPaths resolve on the server, so an HTTP agent reads what is already there:\nfiles under an allow-listed root, or a URL the server fetches. It cannot\nhand over a file from its own machine. It is single-tenant and fails\nclosed: with no auth token and no `[paths]` allow list, the process exits\nrather than serving an open endpoint.\n\nDocker images are published to GHCR for amd64 and arm64, with everything\nbaked in, so every tool works on the first request:\n\n```bash\n./deploy.sh # token, image, start, health-check\ncp your.pdf documents/ # this folder is the server's /data/pdfs\n```\n\nRead **[docs/remote-access.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/remote-access.md)** for the trust\nboundary and threat model before deploying, and\n**[docs/configuration.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/configuration.md#http-transport-setup)**\nfor setup, client config, and token rotation.\n\n## Configuration\n\npdf-mcp works out of the box. To restrict which paths and URL hosts the\nserver may touch, tune cache and worker settings, or add your own\ncontent-trust phrases, see **[docs/configuration.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/configuration.md)**.\n\n## Roadmap\n\nSee [ROADMAP.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/ROADMAP.md) for planned features and release history.\n\n## Contributing\n\nContributions are welcome. See **[docs/contributing.md](https://github.com/jztan/pdf-mcp/blob/develop/docs/contributing.md)** for setup, checks, the coherence eval harness, and quality-loop guidelines.\n\n## Contributors\n\nThank you to everyone who has helped improve this project through code, reviews, testing, and feature requests:\n\n\n[@Summer907](https://github.com/Summer907) · [@ebbsanchez](https://github.com/ebbsanchez) · [@VooDisss](https://github.com/VooDisss) · [@DerDennisOP](https://github.com/DerDennisOP) · [@deepdmk](https://github.com/deepdmk)\n\n\n\n $\"Contributors\"$ \n\n\nPer-release contributor credits are listed in the [Changelog](https://github.com/jztan/pdf-mcp/blob/develop/CHANGELOG.md).\n\n## Security\n\nFound a vulnerability? See [SECURITY.md](https://github.com/jztan/pdf-mcp/blob/develop/SECURITY.md) for the threat model, reporting channel, and expected response timeline. Please do not open a public GitHub issue for unpatched security reports.\n\n## License\n\nMIT. See [LICENSE](https://github.com/jztan/pdf-mcp/blob/develop/LICENSE).\n\n## Links\n\n- [pdf-mcp on PyPI](https://pypi.org/project/pdf-mcp/)\n- [pdf-mcp on GitHub](https://github.com/jztan/pdf-mcp)\n\n## Blog posts\n\n**The story behind the releases.** Building pdf-mcp keeps surprising me: benchmarks that go the wrong way, formats that break everything, features I had to remove. I write about that thinking in [The Dispatch](https://blog.jztan.com/newsletter/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-newsletter). Come along if that's your kind of thing.\n\nBackground, benchmarks, and design notes from building pdf-mcp:\n\n**Getting started**\n\n- [How I Built pdf-mcp](https://blog.jztan.com/how-i-built-pdf-mcp-solving-claude-large-pdf-limitations/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-how-i-built-pdf-mcp-solving-claude-large-pdf-limitations): The problem with large PDFs in AI agents and a working solution\n- [How Claude Code Actually Reads PDFs](https://blog.jztan.com/how-claude-code-actually-reads-pdfs-lessons-from-building-an-mcp-server/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-how-claude-code-actually-reads-pdfs-lessons-from-building-an-mcp-server): How AI agents use pdf-mcp tools to read and navigate PDF documents\n- [How AI Agents Should Read PDFs: 5 Patterns That Survived Production](https://blog.jztan.com/ai-agent-pdf-reading-patterns/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-ai-agent-pdf-reading-patterns): Five production-tested patterns for how agents should navigate PDFs at scale\n\n**Corpus & multi-document search**\n\n- [A Knowledge Base Is Just a Folder](https://blog.jztan.com/ai-agent-pdf-knowledge-base/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-ai-agent-pdf-knowledge-base): Turning a folder of PDFs into an agent knowledge base with the corpus tools, no ingestion pipeline or vector store\n- [Cross-Document Retrieval for AI Agents Without a Vector Database](https://blog.jztan.com/rag-without-vector-database/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-rag-without-vector-database): Why BM25 scores don't merge across per-document indexes but ranks do, and how two-stage RRF puts a gold document in the top 3 on 84.8% of 184 graded queries over a 100-PDF corpus\n\n**Search & retrieval**\n\n- [Semantic vs Keyword Search for AI Agents](https://blog.jztan.com/semantic-vs-keyword-search-ai-agents/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-semantic-vs-keyword-search-ai-agents): Benchmarks and a dual-search routing pattern: FTS5 for exact identifiers, embeddings for natural language\n- [Hybrid Search vs Query Routing for AI Agents](https://blog.jztan.com/hybrid-search-vs-query-routing-ai-agents/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-hybrid-search-vs-query-routing-ai-agents): Why pdf-mcp uses hybrid RRF instead of query routing: benchmarks showing RRF wins across query types\n- [Section Chunking vs Page Chunking for AI Agents](https://blog.jztan.com/section-chunking-vs-page-chunking-ai-agents/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-section-chunking-vs-page-chunking-ai-agents): Why section-aware search delivers full section content in one call while page-mode costs 2–6 extra tool calls per query\n- [Section-Level RAG: Why BM25 Beat Hybrid Search in My Benchmark](https://blog.jztan.com/bm25-vs-hybrid-search-section-rag/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-bm25-vs-hybrid-search-section-rag): Why pdf-mcp's section-grain search is BM25-only: hybrid RRF caused a 33% lexical regression at section grain, so granularity decides the search technique\n- [How One Search Change Eliminated an Entire Agent Step](https://blog.jztan.com/how-paragraph-excerpts-changed-agent-behavior/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-how-paragraph-excerpts-changed-agent-behavior): Switching pdf_search from fixed-width snippets to paragraph excerpts turned it from a pivot tool into a terminal tool: 97% vs 80% answer containment across a 30-query benchmark\n\n**Engineering & security**\n\n- [MCP Server Security: 8 Vulnerabilities](https://blog.jztan.com/mcp-server-security-8-vulnerabilities/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-mcp-server-security-8-vulnerabilities): What we found when we audited an MCP server for security holes\n- [Your LLM Is Free QA for Your MCP Server](https://blog.jztan.com/llm-free-qa-mcp-server/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-llm-free-qa-mcp-server): Four Payload UX bugs in pdf-mcp that schema tests missed but Claude Desktop surfaced during real use\n- [Why Multi-Column PDFs Scramble Reading Order in RAG](https://blog.jztan.com/multi-column-pdf-reading-order/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-multi-column-pdf-reading-order): Fixing two-column extraction (0.564 → 0.816 fidelity), the title-page author-grid regression it caused, and the aggregate metric that stayed blind to both\n- [How I Fixed Vertical Japanese PDF Extraction](https://blog.jztan.com/vertical-japanese-pdf-reading-order/?utm_source=github&utm_medium=referral&utm_campaign=pdf-mcp&utm_content=list-vertical-japanese-pdf-reading-order): Tategaki pages extract scrambled because reading order is geometric, not stored; rebuilding it from glyph positions (columns right to left, characters top to bottom), with no OCR and no new dependency\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_109":110,"_111":112,"_113":114,"_115":116,"_117":118,"_119":120},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102,103,104,105,106,107,108],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","agentic-rag","ai","cjk","claude","claude-code","codex-cli","document-processing","llm","ocr","opencode","pdf","pdf-extraction","pymupdf","python","rag","topics",[94,95,96,97,98,99,100,101,125,126,127,102,103,104,105,106,107,108,128,129],"license","MIT","language","Python","registryName","io.github.jztan/pdf-mcp","homepage","https://pdf-mcp.jztan.com","packages",[121],{"_122":123,"_124":21,"_71":72},"registryType","pypi","identifier","mcp","mcp-server","model-context-protocol","semantic-search","table-extraction","ENV",{"_132":133,"_134":135,"_136":137},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]