mcp-pdf-tokensaver

A layout-aware MCP server that analyzes PDF structures to save up to 90% context tokens for LLMs.

Stop wasting LLM tokens on PDFs. This MCP server provides layout-aware, two-pass chunking and formula protection for Cursor, Claude Desktop, and other AI editors.

Why mcp-pdf-tokensaver?

Reading dense, multi-column technical papers, API documentation, or corporate PDFs inside AI editors often leads to two major frustrations:

1. The Token Tax: Multi-column text gets scrambled, forcing you to upload full documents and waste tens of thousands of context tokens.
2. Formula Corruption: LaTeX equations frequently get broken or mistranslated during full-text ingestion.

mcp-pdf-tokensaver provides a 100% local solution to shield your token window.

Features

• Layout-Aware Inspection: Parse PDF structures (multi-columns, tables, headings) without uploading full text immediately.
• Two-Pass Token Saving: LLMs first inspect the document outline via a condensed JSON schema, then selectively fetch exact text chunks based on blockId.
• 100% Client-Side & Secure: All parsing happens locally. Your sensitive data never leaves your machine.
• Scanned PDF Support: OCR integration for scanned documents (English).

How It Works

Instead of feeding raw PDF streams into the LLM, this server empowers your AI model with a Two-Pass Precise Retrieval Strategy:

1. inspect_pdf_structure: The LLM scans a super-condensed layout skeleton of your PDF, mapping pages, columns, and headings in milliseconds.
2. fetch_pdf_chunks: The LLM target-fetches only the exact text rows or equations it needs based on specific blockIds.

Token Savings Comparison

Solution	Working Principle	Token Impact
Traditional Full-Text	Dumps entire PDF as Markdown into context	🔴 Catastrophic: 40-page doc can burn 30K+ tokens per turn
Vector RAG	Local embedding search, returns top-3 chunks	🟡 Medium: No global document awareness
mcp-pdf-tokensaver	Structure-aware agentic retrieval	🟢 Minimal: Saves 90%+ tokens

Installation

Option 1: Install via npm (Recommended)

npm install -g mcp-pdf-tokensaver

Option 2: Install from source

git clone https://github.com/anthropics/mcp-pdf-tokensaver.git
cd mcp-pdf-tokensaver
npm install
npm run build

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-tokensaver": {
      "command": "mcp-pdf-tokensaver",
      "args": []
    }
  }
}

Cursor / Windsurf

Add to your MCP settings:

{
  "mcpServers": {
    "pdf-tokensaver": {
      "command": "mcp-pdf-tokensaver",
      "args": []
    }
  }
}

Custom Configuration

You can configure limits via environment variables:

{
  "mcpServers": {
    "pdf-tokensaver": {
      "command": "mcp-pdf-tokensaver",
      "args": [],
      "env": {
        "MCP_PDF_MAX_SIZE_MB": "100",
        "MCP_PDF_MAX_PAGES": "500",
        "MCP_OCR_TIMEOUT_MS": "30000"
      }
    }
  }
}

Usage

Once configured, simply ask your AI editor to analyze a PDF:

"Help me analyze the structure of paper.pdf on my desktop. Where are the core formulas?"

The LLM will automatically call inspect_pdf_structure to get a condensed layout skeleton, then use fetch_pdf_chunks to retrieve only the relevant sections.

Tools

inspect_pdf_structure

Analyzes the layout and structural skeleton of a local PDF file.

Input:

{
  "filePath": "/path/to/your/document.pdf"
}

Output:

{
  "status": "success",
  "documentMeta": {
    "path": "/path/to/your/document.pdf",
    "totalPages": 24,
    "isEncrypted": false,
    "hasScannedPages": [],
    "estimatedFullTextTokens": 84000
  },
  "structureSkeleton": [
    {
      "blockId": "page_1_para_1",
      "type": "heading",
      "pageIndex": 0,
      "level": 1,
      "summary": "1. Introduction",
      "tokenEstimate": 8
    },
    {
      "blockId": "page_2_para_3",
      "type": "text",
      "pageIndex": 1,
      "layoutType": "double-column",
      "summary": "Discusses client-side WebAssembly...",
      "tokenEstimate": 45
    }
  ]
}

fetch_pdf_chunks

Selectively fetch specific text paragraphs or equations based on their blockId.

Input:

{
  "filePath": "/path/to/your/document.pdf",
  "blockIds": ["page_2_para_3", "page_4_para_1"]
}

Output:

{
  "status": "success",
  "fetchedChunks": {
    "page_2_para_3": {
      "type": "text",
      "content": "We implement a pure client-side PDF parsing pipeline...",
      "pageContext": "Page 2"
    },
    "page_4_para_1": {
      "type": "equation",
      "content": "$$\\Theta(N) = \\sum_{i=1}^{N} \\alpha_i$$",
      "pageContext": "Page 4"
    }
  }
}

Limitations

• Encrypted PDFs are not supported
• Scanned PDF OCR is limited to English
• Maximum file size: 100MB (configurable)
• Maximum pages: 500 (configurable)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol for the MCP specification
• PDF.js for PDF parsing
• Tesseract.js for OCR capabilities

---

Optimized by the core layout engine of GoLocalPDF — the leading privacy-first client-side PDF utility.

If you need a seamless browser-based PDF reading experience with dual-pane translation, visit golocalpdf.com.