{"_id":"@m.bebars/pdf-mcp-server","name":"@m.bebars/pdf-mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@m.bebars/pdf-mcp-server","version":"1.0.0","description":"MCP server for local PDF extraction — zero AI cost, works offline","type":"module","main":"./build/index.js","bin":{"pdf-mcp-server":"build/index.js"},"scripts":{"build":"tsc && node -e \"const fs=require('fs');const f='build/index.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'))\"","dev":"tsx src/index.ts","start":"node build/index.js","prepare":"npm run build","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","inspector":"npx @modelcontextprotocol/inspector build/index.js"},"keywords":["mcp","modelcontextprotocol","pdf","pdf-extraction","claude","mcp-server","claude-desktop","pdfjs","markdown"],"author":{"name":"Mahmoud Bebars","email":"https://github.com/mahmoud-bebars"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/mahmoud-bebars/pdf-mcp-server.git"},"bugs":{"url":"https://github.com/mahmoud-bebars/pdf-mcp-server/issues"},"homepage":"https://github.com/mahmoud-bebars/pdf-mcp-server#readme","mcpName":"io.github.mahmoud-bebars/pdf-mcp-server","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","pdfjs-dist":"^5.7.284","zod":"^4.4.3"},"devDependencies":{"@types/node":"^25.9.1","@vitest/coverage-v8":"^4.1.7","pdf-lib":"^1.17.1","tsx":"^4.22.3","typescript":"^6.0.3","vitest":"^4.1.7"},"gitHead":"86bfd7e735eadc6db711f422d54bfce801d70bb3","types":"./build/index.d.ts","_id":"@m.bebars/pdf-mcp-server@1.0.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-GbcJJ6CGiLXOcFJ7p7FOzu3De9LFtXNug5R7TncQOF2F1xYIlvPLn6d69eEA0alV2X0ufGDxb1wmrQPvXm75/g==","shasum":"7f6109fa3478c0032011ea405fe665bbc5765c40","tarball":"https://registry.npmjs.org/@m.bebars/pdf-mcp-server/-/pdf-mcp-server-1.0.0.tgz","fileCount":28,"unpackedSize":33950,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFs5zx0TKYRdA4SJb3W4VpdYGynpJEKel4GSnfuxKmNqAiBswsYYkh9T9ytkjdiUMyr+KwOy8I19uAhAKLTqQrIhwA=="}]},"_npmUser":{"name":"m.bebars","email":"mahmoudbebars.me@gmail.com"},"directories":{},"maintainers":[{"name":"m.bebars","email":"mahmoudbebars.me@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pdf-mcp-server_1.0.0_1779540344671_0.2910529248869511"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-23T12:45:44.454Z","1.0.0":"2026-05-23T12:45:44.821Z","modified":"2026-05-23T12:45:45.091Z"},"maintainers":[{"name":"m.bebars","email":"mahmoudbebars.me@gmail.com"}],"description":"MCP server for local PDF extraction — zero AI cost, works offline","homepage":"https://github.com/mahmoud-bebars/pdf-mcp-server#readme","keywords":["mcp","modelcontextprotocol","pdf","pdf-extraction","claude","mcp-server","claude-desktop","pdfjs","markdown"],"repository":{"type":"git","url":"git+https://github.com/mahmoud-bebars/pdf-mcp-server.git"},"author":{"name":"Mahmoud Bebars","email":"https://github.com/mahmoud-bebars"},"bugs":{"url":"https://github.com/mahmoud-bebars/pdf-mcp-server/issues"},"license":"MIT","readme":"# pdf-mcp-server\n\n**A local MCP server that gives Claude the ability to extract PDFs offline — zero AI tokens spent on parsing.**\n\n---\n\n## What It Does\n\nEvery 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.\n\npdf-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.\n\n```\nWithout pdf-mcp-server:\nUser attaches PDF → Claude decodes ~15,000 tokens → Claude answers\n\nWith pdf-mcp-server:\nUser attaches PDF → tool extracts locally (0 tokens) → Claude reads ~3,500 tokens → Claude answers\n```\n\n---\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `pdf_extract_markdown` | Extract full PDF as clean Markdown. Claude uses this automatically. |\n| `pdf_extract_plain_text` | Extract as plain text. Maximum token compression. |\n| `pdf_get_metadata` | Get page count, title, author, size — without full extraction. |\n| `pdf_extract_pages` | Extract a specific page range. For large documents. |\n\n---\n\n## Requirements\n\n- Node.js 18+\n- Claude Desktop (or any MCP-compatible client)\n- No API key needed — runs fully offline\n\n---\n\n## Installation\n\n### Option A: npx (no install)\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"pdf-mcp-server\"]\n    }\n  }\n}\n```\n\n### Option B: Local clone\n\n```bash\ngit clone https://github.com/mahmoud-bebars/pdf-mcp-server\ncd pdf-mcp-server\nnpm install\nnpm run build\n```\n\nThen add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"pdf-mcp-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/pdf-mcp-server/build/index.js\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The tools are now available.\n\n---\n\n## Usage\n\nOnce installed, Claude uses the tools automatically. You don't need to ask.\n\nJust say:\n\n- \"Summarize this PDF: /Users/bob/reports/q3-report.pdf\"\n- \"What are the key findings in /home/bob/research.pdf?\"\n- \"Extract pages 5-20 from /docs/manual.pdf and explain the setup process\"\n\nClaude will call `pdf_extract_markdown` or `pdf_get_metadata` as needed without being prompted.\n\n---\n\n## Token Savings\n\n| Document | Raw PDF tokens | After extraction | Savings |\n|---------|---------------|-----------------|---------|\n| 10-page report | ~15,000 | ~3,500 | 77% |\n| 50-page technical doc | ~75,000 | ~18,000 | 76% |\n| 2-page form | ~3,000 | ~600 | 80% |\n\nEstimates vary by PDF content density.\n\n---\n\n## Limitations\n\n- Scanned PDFs (image-only, no text layer) cannot be extracted — the tool returns a clear error explaining this\n- Diagrams and charts are not included in the output — only text content\n- Very large PDFs (100MB+) are rejected — use `pdf_extract_pages` for large documents\n- Encrypted PDFs with password protection will fail extraction\n\n---\n\n## Development\n\n```bash\nnpm run dev       # run with tsx (no build needed)\nnpm run build     # compile TypeScript\nnpm test          # run all tests\nnpm run test:coverage  # coverage report\n```\n\n### Testing with MCP Inspector\n\n```bash\nnpm run build\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n---\n\n## Project Structure\n\n```\nsrc/\n  index.ts          # Entry point\n  constants.ts      # Shared constants\n  types.ts          # TypeScript interfaces\n  tools/            # One file per MCP tool\n  services/         # pdf.js extraction, file validation\n  schemas/          # Zod input schemas\n  utils/            # Formatters, error messages\ntests/\n  unit/             # Pure function tests\n  integration/      # Service-level tests with real PDFs\n  e2e/              # MCP protocol tests\n  fixtures/         # Test PDF files\n```\n\n---\n\n## Built By\n\nMahmoud Bebars\n[mahmoudbebars.dev](https://mahmoudbebars.dev) | [GitHub](https://github.com/mahmoud-bebars) | [LinkedIn](https://www.linkedin.com/in/mbebars/)\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-fc307a42331aa25f557979f2f883f233"}