📄 @sylphx/pdf-reader-mcp

Production-ready PDF processing server for AI agents

5-10x faster parallel processing • Y-coordinate content ordering • 94%+ test coverage • 103 tests passing

PDF Reader MCP is a production-ready Model Context Protocol server that empowers AI agents with enterprise-grade PDF processing capabilities. Extract text, images, and metadata with unmatched performance and reliability.

The Problem:

// Traditional PDF processing
- Sequential page processing (slow)
- No natural content ordering
- Complex path handling
- Poor error isolation

The Solution:

// PDF Reader MCP
- 5-10x faster parallel processing ⚡
- Y-coordinate based ordering 📐
- Flexible path support (absolute/relative) 🎯
- Per-page error resilience 🛡️
- 94%+ test coverage ✅

Result: Production-ready PDF processing that scales.

• 🚀 5-10x faster than sequential with automatic parallelization
• ⚡ 12,933 ops/sec error handling, 5,575 ops/sec text extraction
• 💨 Process 50-page PDFs in seconds with multi-core utilization
• 📦 Lightweight with minimal dependencies

• 🎯 Path Flexibility - Absolute & relative paths, Windows/Unix support (v1.3.0)
• 🖼️ Smart Ordering - Y-coordinate based content preserves document layout
• 🛡️ Type Safe - Full TypeScript with strict mode enabled
• 📚 Battle-tested - 103 tests, 94%+ coverage, 98%+ function coverage
• 🎨 Simple API - Single tool handles all operations elegantly

Real-world performance from production testing:

Benchmarks vary based on PDF complexity and system resources.

claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

code --add-mcp '{"name":"pdf-reader","command":"npx","args":["@sylphx/pdf-reader-mcp"]}'

1. Open Settings → MCP → Add new MCP Server
2. Select Command type
3. Enter: npx @sylphx/pdf-reader-mcp

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

Add to Cline's MCP settings:

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

1. Go to Settings → AI → Manage MCP Servers → Add
2. Command: npx, Args: @sylphx/pdf-reader-mcp

npx -y @smithery/cli install @sylphx/pdf-reader-mcp --client claude

# Quick start - zero installation
npx @sylphx/pdf-reader-mcp

# Or install globally
npm install -g @sylphx/pdf-reader-mcp

{
  "sources": [{
    "path": "documents/report.pdf"
  }],
  "include_full_text": true,
  "include_metadata": true,
  "include_page_count": true
}

Result:

• ✅ Full text content extracted
• ✅ PDF metadata (author, title, dates)
• ✅ Total page count
• ✅ Structural sharing - unchanged parts preserved

{
  "sources": [{
    "path": "documents/manual.pdf",
    "pages": "1-5,10,15-20"
  }],
  "include_full_text": true
}

// Windows - Both formats work!
{
  "sources": [{
    "path": "C:\\Users\\John\\Documents\\report.pdf"
  }],
  "include_full_text": true
}

// Unix/Mac
{
  "sources": [{
    "path": "/home/user/documents/contract.pdf"
  }],
  "include_full_text": true
}

No more "Absolute paths are not allowed" errors!

{
  "sources": [{
    "path": "presentation.pdf",
    "pages": [1, 2, 3]
  }],
  "include_images": true,
  "include_full_text": true
}

Response includes:

• Text and images in exact document order (Y-coordinate sorted)
• Base64-encoded images with metadata (width, height, format)
• Natural reading flow preserved for AI comprehension

{
  "sources": [
    { "path": "C:\\Reports\\Q1.pdf", "pages": "1-10" },
    { "path": "/home/user/Q2.pdf", "pages": "1-10" },
    { "url": "https://example.com/Q3.pdf" }
  ],
  "include_full_text": true
}

⚡ All PDFs processed in parallel automatically!

• ✅ Text Extraction - Full document or specific pages with intelligent parsing
• ✅ Image Extraction - Base64-encoded with complete metadata (width, height, format)
• ✅ Content Ordering - Y-coordinate based layout preservation for natural reading flow
• ✅ Metadata Extraction - Author, title, creation date, and custom properties
• ✅ Page Counting - Fast enumeration without loading full content
• ✅ Dual Sources - Local files (absolute or relative paths) and HTTP/HTTPS URLs
• ✅ Batch Processing - Multiple PDFs processed concurrently

• ⚡ 5-10x Performance - Parallel page processing with Promise.all
• 🎯 Smart Pagination - Extract ranges like "1-5,10-15,20"
• 🖼️ Multi-Format Images - RGB, RGBA, Grayscale with automatic detection
• 🛡️ Path Flexibility - Windows, Unix, and relative paths all supported (v1.3.0)
• 🔍 Error Resilience - Per-page error isolation with detailed messages
• 📏 Large File Support - Efficient streaming and memory management
• 📝 Type Safe - Full TypeScript with strict mode enabled

// ✅ Windows
{ "path": "C:\\Users\\John\\Documents\\report.pdf" }
{ "path": "C:/Users/John/Documents/report.pdf" }

// ✅ Unix/Mac
{ "path": "/home/john/documents/report.pdf" }
{ "path": "/Users/john/Documents/report.pdf" }

// ✅ Relative (still works)
{ "path": "documents/report.pdf" }

Other Improvements:

• 🐛 Fixed Zod validation error handling
• 📦 Updated all dependencies to latest versions
• ✅ 103 tests passing, 94%+ coverage maintained

The single tool that handles all PDF operations.

{
  path?: string;        // Local file path (absolute or relative)
  url?: string;         // HTTP/HTTPS URL to PDF
  pages?: string | number[];  // Pages to extract: "1-5,10" or [1,2,3]
}

Metadata only (fast):

{
  "sources": [{ "path": "large.pdf" }],
  "include_metadata": true,
  "include_page_count": true,
  "include_full_text": false
}

From URL:

{
  "sources": [{
    "url": "https://arxiv.org/pdf/2301.00001.pdf"
  }],
  "include_full_text": true
}

Page ranges:

{
  "sources": [{
    "path": "manual.pdf",
    "pages": "1-5,10-15,20"  // Pages 1,2,3,4,5,10,11,12,13,14,15,20
  }]
}

Document Layout:
┌─────────────────────┐
│ [Title]       Y:100 │
│ [Image]       Y:150 │
│ [Text]        Y:400 │
│ [Photo A]     Y:500 │
│ [Photo B]     Y:550 │
└─────────────────────┘

Response Order:
[
  { type: "text", text: "Title..." },
  { type: "image", data: "..." },
  { type: "text", text: "..." },
  { type: "image", data: "..." },
  { type: "image", data: "..." }
]

{
  "sources": [{ "path": "manual.pdf" }],
  "include_images": true
}

{
  "images": [{
    "page": 1,
    "index": 0,
    "width": 1920,
    "height": 1080,
    "format": "rgb",
    "data": "base64-encoded-png..."
  }]
}

{ "path": "C:\\Users\\John\\file.pdf" }
{ "path": "/home/user/file.pdf" }

{ "path": "docs/report.pdf" }
{ "path": "./2024/Q1.pdf" }

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"],
      "cwd": "/path/to/documents"
    }
  }
}

{ "sources": [{ "path": "big.pdf", "pages": "1-20" }] }

// Step 1: Get page count
{ "sources": [{ "path": "big.pdf" }], "include_full_text": false }

// Step 2: Extract sections
{ "sources": [{ "path": "big.pdf", "pages": "50-75" }] }

{
  "sources": [
    { "path": "big.pdf", "pages": "1-50" },
    { "path": "big.pdf", "pages": "51-100" }
  ]
}

Solution: Upgrade to v1.3.0+

npm update @sylphx/pdf-reader-mcp

Restart your MCP client completely.

Causes:

• File doesn't exist at path
• Wrong working directory
• Permission issues

Solutions:

Use absolute path:

{ "path": "C:\\Full\\Path\\file.pdf" }

Or configure cwd:

{
  "pdf-reader-mcp": {
    "command": "npx",
    "args": ["@sylphx/pdf-reader-mcp"],
    "cwd": "/path/to/docs"
  }
}

Solution:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install @sylphx/pdf-reader-mcp@latest

Restart MCP client completely.

By default, PDF Reader MCP uses stdio transport for local use. You can also run it as an HTTP server for remote access from multiple machines.

# Run as HTTP server on port 8080
MCP_TRANSPORT=http npx @sylphx/pdf-reader-mcp

FROM oven/bun:1
WORKDIR /app
RUN bun add @sylphx/pdf-reader-mcp
ENV MCP_TRANSPORT=http
ENV MCP_HTTP_PORT=8080
EXPOSE 8080
CMD ["bun", "node_modules/@sylphx/pdf-reader-mcp/dist/index.js"]

{
  "servers": {
    "pdf-reader": {
      "type": "http",
      "url": "https://your-server.com/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

• 🔒 Security First - Flexible paths with secure defaults
• 🎯 Simple Interface - One tool, all operations
• ⚡ Performance - Parallel processing, efficient memory
• 🛡️ Reliability - Per-page isolation, detailed errors
• 🧪 Quality - 94%+ coverage, strict TypeScript
• 📝 Type Safety - No any types, strict mode
• 🔄 Backward Compatible - Smooth upgrades always

git clone https://github.com/SylphxAI/pdf-reader-mcp.git
cd pdf-reader-mcp
pnpm install && pnpm build

pnpm run build       # Build TypeScript
pnpm run test        # Run 103 tests
pnpm run test:cov    # Coverage (94%+)
pnpm run check       # Lint + format
pnpm run check:fix   # Auto-fix
pnpm run benchmark   # Performance tests

feat(images): add WebP support
fix(paths): handle UNC paths
docs(readme): update examples

• 📖 Full Docs - Complete guides
• 🚀 Getting Started - Quick start
• 📘 API Reference - Detailed API
• 🏗️ Design - Architecture
• ⚡ Performance - Benchmarks
• 🔍 Comparison - vs. alternatives

✅ Completed

• Image extraction (v1.1.0)
• 5-10x parallel speedup (v1.1.0)
• Y-coordinate ordering (v1.2.0)
• Absolute paths (v1.3.0)
• 94%+ test coverage (v1.3.0)

🚀 Next

• OCR for scanned PDFs
• Annotation extraction
• Form field extraction
• Table detection
• 100+ MB streaming
• Advanced caching
• PDF generation

Vote at Discussions

Featured on:

• Smithery - MCP directory
• Glama - AI marketplace
• MseeP.ai - Security validated

Trusted worldwide • Enterprise adoption • Battle-tested

Show Your Support: ⭐ Star • 👀 Watch • 🐛 Report bugs • 💡 Suggest features • 🔀 Contribute

103 Tests • 94%+ Coverage • Production Ready

MIT © Sylphx

Built with:

• PDF.js - Mozilla PDF engine
• Bun - Fast JavaScript runtime

Special thanks to the open source community ❤️

This project uses the following @sylphx packages:

• @sylphx/mcp-server-sdk - MCP server framework
• @sylphx/vex - Schema validation
• @sylphx/biome-config - Biome configuration
• @sylphx/tsconfig - TypeScript configuration
• @sylphx/bump - Version management
• @sylphx/doctor - Project health checker