Extract text from local PDF documents with optional pluggable OCR support in a read-only, sandboxed environment.
Also known as sezzlee/mcp, pdf, @sezzlee/pdf-mcp
- Stars
- 1
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 0.1.2
- Last commit
- Nov 13, 2026
- License
- MIT
What is Sezzlee PDF MCP?
Sezzlee PDF extracts text from local PDF documents with optional pluggable OCR support in a read-only, sandboxed environment. It exposes 4 tools, such as list_documents, describe_document, read_pages.
Summary generated from the project's README
About Sezzlee PDF MCP server
Sezzlee PDF provides a sandboxed, read-only environment for extracting text from local PDF documents. Designed for developers who need to process files without network exposure, the server operates entirely locally. It uses @firecrawl/pdf-inspector for text extraction and manages files within a specified sandbox root to ensure security. Users can interact with their documents through tools like list_documents, describe_document, read_pages, and find_in_document.
While the server does not perform optical character recognition itself, it supports pluggable OCR through injected modules. By providing a custom module via the --ocr flag, you can connect the server to external providers like Ollama to handle scanned pages. This setup allows the server to render pages that lack a text layer and pass them to a provider for transcription. The system includes a document cache to store extracted Markdown, helping to manage memory and performance during repeated requests.
What you can do with it
- 1List available PDF filesAn AI client can scan a specific directory to find all readable PDF documents.
- 2Extract specific page contentA developer can request the Markdown text from a specific range of pages within a document.
- 3Search for text within documentsYou can perform a literal search across a PDF to find specific queries and their context.
- 4Process scanned documents with OCRThe server can use an external module to transcribe pages that do not have a text layer.
Written from the project's README. Every use case is checked against a quote from it.
How to install Sezzlee PDF MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Sezzlee PDF MCP in Claude Code
$ claude mcp add pdf -- npx -y @sezzlee/pdf-mcp /path/to/folderInstall Sezzlee PDF MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pdf": {
"command": "npx",
"args": [
"-y",
"@sezzlee/pdf-mcp",
"/path/to/folder"
]
}
}
}Install Sezzlee PDF MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pdf": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@sezzlee/pdf-mcp",
"/path/to/folder"
]
}
}
}Install Sezzlee PDF MCP in VS Code CLI
$ code --add-mcp '{"name":"pdf","type":"stdio","command":"npx","args":["-y","@sezzlee/pdf-mcp","/path/to/folder"]}'Install Sezzlee PDF MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"pdf": {
"command": "npx",
"args": [
"-y",
"@sezzlee/pdf-mcp",
"/path/to/folder"
]
}
}
}Install Sezzlee PDF MCP in Codex
$ codex mcp add pdf -- npx -y @sezzlee/pdf-mcp /path/to/folderInstall Sezzlee PDF MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pdf] command = "npx" args = ["-y", "@sezzlee/pdf-mcp", "/path/to/folder"]
Install Sezzlee PDF MCP in Gemini CLI
$ gemini mcp add -s user pdf npx -- -y @sezzlee/pdf-mcp /path/to/folderInstall Sezzlee PDF MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pdf": {
"command": "npx",
"args": [
"-y",
"@sezzlee/pdf-mcp",
"/path/to/folder"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @sezzlee/pdf-mcp 0.1.2 in an isolated container with no network and no keys. It answered and listed 4 tools.
Sezzlee PDF MCP tools 4
Read from the server with tools/listlist_documentsRead-onlyList readable PDF documents under the server root. Returns filePath values that other tools accept verbatim. The listing never opens a file, so a listed path is a candidate, not a guarantee that the document parses. totalExact distinguishes a complete total; scanTruncated is separate from the result page limit.
describe_documentRead-onlySummarise one PDF: page count, document type, which pages carry no trustworthy text, and what this server can do with it. pagesNeedingOcr is determined per page from the extracted text. documentType and classificationConfidence come from a separate document-level classifier: the confidence scores that verdict, NOT the accuracy of any extracted text, and the classifier reports a whole document as image-based when a single page is a scan. Calling this first is optional; read_pages and find_in_document work from filePath alone.
read_pagesRead-onlyRead selected pages as Markdown, one entry per page, with page numbers counted from 1. A page whose text the engine could not trust is returned with needsOcr true rather than omitted, so a scanned page is never presented as an empty one; empty distinguishes a genuinely blank page from an unreadable one. Each page reports source: text when the PDF's own text layer was used, ocr when a provider transcribed it. A page whose Markdown does not fit the response budget is clamped and marked truncatedMarkdown; nextCursor then resumes inside that page. With an explicit pages selection, nextCursor stays within the selected pages.
find_in_documentRead-onlyFind literal text in the extracted page text. The query is matched literally, never as a regular expression or a query language. Pages that need OCR carry no searchable text and are counted in unsearchablePages: when coverageComplete is false, an empty match list means the text was not found in the pages that could be read, NOT that it is absent from the document. Pass ocr to transcribe those pages first and search them too. Case-insensitive matching folds ASCII letters only.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesezzlee/mcp is public and reachablegithub.com/sezzlee/mcp ↗Pass
- Package names this repository as its source@sezzlee/pdf-mcp names sezzlee/mcp as sourcenpmjs.com/package/@sezzlee/pdf-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @sezzlee/pdf-mcpnpmjs.com/package/@sezzlee/pdf-mcp/v/0.1.2#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/sezzlee/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @sezzlee/pdf-mcpPass
- No critical advisory in the package or its dependencies14 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@sezzlee/pdf-mcp
A read-only, sandboxed MCP server for local PDF documents. It builds on @sezzlee/file-core,
which supplies sandbox path resolution, the response budget, the error envelope, cursors and the
document cache. Text extraction uses @firecrawl/pdf-inspector. The server never reaches the
network: OCR is optional, and when it is enabled, the connection decision belongs entirely to
whoever supplies the two injected ports.
Quick start
{
"mcpServers": {
"pdf": {
"command": "npx",
"args": ["-y", "@sezzlee/pdf-mcp", "/path/to/documents"]
}
}
}
To enable OCR, point --ocr at a module whose default export is an OcrBinding (see
Configuration and OCR):
{
"mcpServers": {
"pdf": {
"command": "npx",
"args": [
"-y",
"@sezzlee/pdf-mcp",
"/path/to/documents",
"--ocr",
"/path/to/ollama-binding.js"
]
}
}
}
Tools
| Tool | What it does | Key arguments |
|---|---|---|
list_documents |
Lists readable PDF candidates under the root; never opens a file | subdirectory, pattern, maxResults |
describe_document |
Page count, document type, per-page OCR need, server capabilities | filePath |
read_pages |
Reads selected pages as Markdown, page numbers 1-based | filePath, pages, maxPages, ocr, cursor |
find_in_document |
Literal search over extracted text, with page number and match context | filePath, query, matchMode, caseSensitive, ocr, cursor |
If the file path is already known, describe_document is optional: read_pages and
find_in_document work from filePath alone.
Configuration
CLI (sezzlee-pdf <pdf-source-root> [--ocr <module>]):
| Argument | Default | Meaning |
|---|---|---|
<pdf-source-root> |
required | Sandbox root; every readable path is resolved and checked against it. |
--ocr <module> |
none | Path or package specifier to a module whose default export is { rasterizer, provider }. Absent means no OCR: read_pages/find_in_document refuse ocr: true and describe_document reports capabilities.ocr: false. |
Programmatic (createPdfMcpServer(root, options)):
| Option | Default | Meaning |
|---|---|---|
documentCacheSize |
2 |
Extracted documents held in memory at once, 1–16. A budget, not a guard: each cached document holds every page's Markdown on the heap. |
maxConcurrentListings |
4 |
Concurrent list_documents calls before a request is refused. |
maxConcurrentExtractions |
2 |
Concurrent PDF extractions before a request is refused. |
ocr |
none | An OcrBinding ({ rasterizer, provider, dpi?, maxPagesPerCall?, timeoutMs? }). Neither port is a dependency of this package. |
OCR
The server does not perform OCR; it supports it. Two ports are injected — neither the raster library nor the model client is a dependency of this package.
interface PageRasterizer {
render(job: {
bytes: Buffer;
pages: readonly number[];
dpi: number;
signal?: AbortSignal;
}): Promise<readonly RenderedPage[]>; // { page, image, mediaType }
}
interface OcrProvider {
readonly name: string;
recognize(job: {
pages: readonly RenderedPage[];
signal?: AbortSignal;
}): Promise<readonly RecognizedPage[]>; // { page, markdown, confidence? }
}
The server does exactly this: it renders the pages the text layer could not answer, recognizes
the resulting images, substitutes the result for that page, and marks it source: "ocr".
Programmatic binding:
createPdfMcpServer(root, {
ocr: { rasterizer: pdfjsRasterizer, provider: ollamaProvider, dpi: 200 },
});
CLI binding — a module whose default export matches OcrBinding, loaded with --ocr <module>
(see examples/ollama-binding.ts in this package for a working example built from
@sezzlee/pdf-raster-pdfjs and @sezzlee/ocr-ollama):
import { createPdfjsRasterizer } from "@sezzlee/pdf-raster-pdfjs";
import { createOllamaOcrProvider } from "@sezzlee/ocr-ollama";
import type { OcrBinding } from "@sezzlee/pdf-mcp";
const binding: OcrBinding = {
rasterizer: createPdfjsRasterizer(),
provider: createOllamaOcrProvider({
baseUrl: process.env["SEZZLEE_PDF_OCR_URL"] ?? "http://127.0.0.1:11434",
model: process.env["SEZZLEE_PDF_OCR_MODEL"] ?? "deepseek-ocr:3b",
}),
dpi: 200,
};
export default binding;
OCR rules
ocr: truewith no provider bound is an error (ocr_unavailable), never a silent fall back to the text layer. Otherwise an agent that asked for OCR could mistake "nobody transcribed this document" for "no match".describe_document→capabilities.ocrreports whether one is bound.- An empty transcription does not count as an answer. If the provider returns empty text, the
page stays
needsOcr— "the model returned nothing" is not the same as "this page is blank". - An unrequested page is ignored. The ports may reorder, skip, or invent pages; results are matched to the page number that was requested, so a provider cannot overwrite a page the text layer already trusted.
- Bytes leave the process. Binding a provider means those pages' pixels go somewhere else. OCR therefore defaults to off and is requested explicitly on every call.
- A page is not re-transcribed on every call. Transcriptions are cached by document fingerprint plus page number. The cache is not a progress log: a search sends only the pages after the cursor to OCR and carries coverage forward in the cursor, so even a large document is eventually walked to the end from cache.
- An expired job does not release its slot. Neither the engine nor an injected port can cancel work that has already started; the slot stays held until the work actually finishes. A provider that never returns can only be recovered by restarting the server — reclaiming the slot on a timer would only postpone the limit.
Rules
- Every page number on the public surface is 1-based. The underlying library returns some
fields 0-based and others 1-based within the same result object. The whole conversion lives in
src/engine/, and lint bans importing@firecrawl/pdf-inspectoroutside that folder — a second import site would reintroduce the bug (measured on 1.23.0:PageMarkdownResult.pageis 0-based, siblingpagesNeedingOcris 1-based). - Page selection is validated before it reaches the library. An out-of-range index otherwise
comes back as a phantom page marked
needsOcr; a negative index wraps through u32. Both would look like a real page to the agent. describe_documentnever builds its OCR page list from the classifier.classifyPdfmarks every page of a document that contains a single scanned page. The list comes from the per-page extraction instead.classificationConfidenceis confidence in the classifier's own verdict, not in any extracted text's accuracy.- An unreadable page is never presented as an empty one. A scanned page returns
needsOcr: true;emptyistrueonly for a page the engine trusted and found genuinely blank. - Search coverage is reported on every response. When any page needs OCR,
coverageCompleteisfalse, and an empty match list is not proof the query is absent from the whole document. - A document is extracted once, in full; the response is paginated. Measurement showed that
requesting a single page cuts extraction cost by a third, not 200-fold — the fixed cost
dominates. Cursor identity depends on document content and OCR mode, not page size. An explicit
pagesselection is preserved across a cursor: it carries forward the rest of that selection and never wanders into unselected pages. A cursor resuming inside a page carries that page's text fingerprint; if the text changed since transcription, the response isstale_cursorrather than silently skipping content. - The server never reaches the network.
fetch,node:http,node:netand their siblings are lint-banned insidesrc/, and the ban is repeated in every layer's override — a later oxlint override replacesno-restricted-importsrather than merging with it, so a single top-level ban would not apply everywhere. - Platform support is narrow. The engine ships no
darwin-x64binary and its wasm fallback is unpublished. On an unsupported host the server stops at startup with a one-line message (exit code 3).
Development
pnpm turbo run build --filter=@sezzlee/pdf-mcp
node packages/servers/pdf-mcp/dist/cli.js /path/to/documents
Tests: pnpm turbo run test --filter=@sezzlee/pdf-mcp (Vitest). A live-Ollama suite
(test/ocr-live.spec.ts) is skipped unless SEZZLEE_PDF_OCR_URL is set; it also reads
SEZZLEE_PDF_OCR_MODEL (default deepseek-ocr:3b). Everything else in test/ocr.spec.ts runs
against fake ports; the live suite only proves the two real adapters compose.
Sezzlee PDF MCP questions
How do I add Sezzlee PDF MCP to Claude Code?
Run claude mcp add pdf -- npx -y @sezzlee/pdf-mcp /path/to/folder in your terminal. Add --scope user to make it available in every project.
How do I add Sezzlee PDF MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Sezzlee PDF MCP provide?
It exposes 4 tools, including list_documents, describe_document, read_pages, find_in_document.
Does this server connect to the internet?
No, the server is designed to be read-only and never reaches the network.
How can I enable OCR functionality?
You can enable OCR by pointing the --ocr argument to a module that exports an OcrBinding.
Is the OCR process automatic?
No, OCR is optional and must be explicitly requested on every call; it defaults to off.