# mcp-pdf-tokensaver

[![mcp-pdf-tokensaver MCP server](https://glama.ai/mcp/servers/xiongxingzhe/mcp-pdf-tokensaver/badges/card.svg)](https://glama.ai/mcp/servers/xiongxingzhe/mcp-pdf-tokensaver)
[![mcp-pdf-tokensaver score](https://glama.ai/mcp/servers/xiongxingzhe/mcp-pdf-tokensaver/badges/score.svg)](https://glama.ai/mcp/servers/xiongxingzhe/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.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-brightgreen.svg)](https://modelcontextprotocol.io)
[![npm](https://img.shields.io/npm/v/mcp-pdf-tokensaver.svg)](https://www.npmjs.com/package/mcp-pdf-tokensaver)

## 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)

```bash
npm install -g mcp-pdf-tokensaver
```

### Option 2: Install from source

```bash
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`:

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

### Cursor / Windsurf

Add to your MCP settings:

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

### Custom Configuration

You can configure limits via environment variables:

```json
{
  "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:**
```json
{
  "filePath": "/path/to/your/document.pdf"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "filePath": "/path/to/your/document.pdf",
  "blockIds": ["page_2_para_3", "page_4_para_1"]
}
```

**Output:**
```json
{
  "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](LICENSE) file for details.

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification
- [PDF.js](https://mozilla.github.io/pdf.js/) for PDF parsing
- [Tesseract.js](https://tesseract.projectnaptha.com/) for OCR capabilities

---

**Optimized by the core layout engine of [GoLocalPDF](https://golocalpdf.com) — 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](https://golocalpdf.com).