pdf-mcp-server

A local MCP server that gives Claude the ability to extract PDFs offline — zero AI tokens spent on parsing.

---

What It Does

Every time Claude receives a raw PDF, it spends tokens decoding the binary structure before it can read the content. On a 50-page document that overhead can reach 75,000 tokens — before Claude has answered a single question.

pdf-mcp-server eliminates that cost entirely. It runs locally on your machine, intercepts PDF files when Claude needs them, extracts clean Markdown using pdf.js, and hands the result back to Claude as plain text. Claude then only spends tokens on the actual task.

Without pdf-mcp-server:
User attaches PDF → Claude decodes ~15,000 tokens → Claude answers

With pdf-mcp-server:
User attaches PDF → tool extracts locally (0 tokens) → Claude reads ~3,500 tokens → Claude answers

---

Tools

Tool	Description
pdf_extract_markdown	Extract full PDF as clean Markdown. Claude uses this automatically.
pdf_extract_plain_text	Extract as plain text. Maximum token compression.
pdf_get_metadata	Get page count, title, author, size — without full extraction.
pdf_extract_pages	Extract a specific page range. For large documents.

---

Requirements

• Node.js 18+
• Claude Desktop (or any MCP-compatible client)
• No API key needed — runs fully offline

---

Installation

Option A: npx (no install)

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

Option B: Local clone

git clone https://github.com/mahmoud-bebars/pdf-mcp-server
cd pdf-mcp-server
npm install
npm run build

Then add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pdf-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/pdf-mcp-server/build/index.js"]
    }
  }
}

Restart Claude Desktop. The tools are now available.

---

Usage

Once installed, Claude uses the tools automatically. You don't need to ask.

Just say:

• "Summarize this PDF: /Users/bob/reports/q3-report.pdf"
• "What are the key findings in /home/bob/research.pdf?"
• "Extract pages 5-20 from /docs/manual.pdf and explain the setup process"

Claude will call pdf_extract_markdown or pdf_get_metadata as needed without being prompted.

---

Token Savings

Document	Raw PDF tokens	After extraction	Savings
10-page report	~15,000	~3,500	77%
50-page technical doc	~75,000	~18,000	76%
2-page form	~3,000	~600	80%

Estimates vary by PDF content density.

---

Limitations

• Scanned PDFs (image-only, no text layer) cannot be extracted — the tool returns a clear error explaining this
• Diagrams and charts are not included in the output — only text content
• Very large PDFs (100MB+) are rejected — use pdf_extract_pages for large documents
• Encrypted PDFs with password protection will fail extraction

---

Development

npm run dev       # run with tsx (no build needed)
npm run build     # compile TypeScript
npm test          # run all tests
npm run test:coverage  # coverage report

Testing with MCP Inspector

npm run build
npx @modelcontextprotocol/inspector node build/index.js

---

Project Structure

src/
  index.ts          # Entry point
  constants.ts      # Shared constants
  types.ts          # TypeScript interfaces
  tools/            # One file per MCP tool
  services/         # pdf.js extraction, file validation
  schemas/          # Zod input schemas
  utils/            # Formatters, error messages
tests/
  unit/             # Pure function tests
  integration/      # Service-level tests with real PDFs
  e2e/              # MCP protocol tests
  fixtures/         # Test PDF files

---

Built By

Mahmoud Bebars mahmoudbebars.dev | GitHub | LinkedIn

---

License

MIT