PDF Processor MCP Server

Professional MCP server that converts PDFs to markdown using intelligent academic paper detection and dual processing engines optimized for Claude Code analysis.

Features

• Intelligent Processing: Auto-detects academic papers for optimal conversion
• Dual Engines: marker-pdf for academic content, PyMuPDF for general documents
• Smart Caching: Hash-based caching prevents redundant processing
• Robust Downloads: Browser headers, redirect handling, content validation
• Local File Support: Process local PDFs via file:// URLs
• Batch Processing: Convert multiple PDFs in single operations

Installation

Quick Setup (Recommended)

# 1. Navigate to the project directory
cd pdf-processor

# 2. Create a virtual environment
python3 -m venv venv

# 3. Activate the virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 4. Install dependencies
pip install -r mcp_requirements.txt

# 5. Verify setup
python3 verify_setup.py

The MCP config is already set up to use the virtual environment. After installation, you can use:

claude code --mcp-config /path/to/pdf-processor/mcp-config.json

Manual Installation

If you prefer not to use a virtual environment:

pip install --user -r mcp_requirements.txt

Then update mcp-config.json line 4 to use your system Python:

"command": "python3",

Verification

Run the verification script to check your setup:

python3 verify_setup.py

This will check:

• ✓ Python version compatibility
• ✓ All required dependencies
• ✓ MCP configuration validity
• ✓ Server script functionality
• ✓ MCP protocol communication

Configuration

The included mcp-config.json is pre-configured and ready to use. It points to the virtual environment Python by default.

Custom Configuration

To add to your own Claude MCP config:

{
  "mcpServers": {
    "pdf-processor": {
      "command": "/absolute/path/to/pdf-processor/venv/bin/python3",
      "args": ["/absolute/path/to/pdf-processor/src/mcp_pdf_server.py"],
      "cwd": "/absolute/path/to/pdf-processor",
      "env": {
        "PYTHONPATH": "/absolute/path/to/pdf-processor/src",
        "PYTHONUNBUFFERED": "1",
        "PYTHONWARNINGS": "ignore::DeprecationWarning"
      }
    }
  }
}

Available Tools

Tool	Purpose	Parameters
convert_pdf_url	Auto-enhanced conversion	url (http/https/file), include_metadata
convert_pdf_url_enhanced	Force marker-pdf processing	url (http/https/file), fallback_to_pymupdf
convert_pdf_url_with_method	Manual method selection	url (http/https/file), method
convert_pdf_pages	Extract a page range	url (http/https/file), start_page, end_page
find_and_convert_main_pdf	Locate the primary PDF on a page, then convert	url
crawl_pdf_links	Extract PDF links from pages	url, max_depth
batch_convert_pdfs	Process multiple PDFs	urls (http/https/file), include_metadata

URL Support

All PDF conversion tools support multiple URL schemes:

• HTTP/HTTPS: Remote PDFs from web servers
• file://: Local PDF files (e.g., file:///path/to/document.pdf)

Processing Engines

Engine	Best For	Speed	Quality
marker-pdf	Academic papers	10-90s	Superior
PyMuPDF	General documents	~0.2s	Standard
Auto	Mixed content	Variable	Optimal

Development

# Run tests
pytest

# Check warning management
python scripts/warning_management.py

Requirements: Python 3.8+

Project Structure

src/mcp_pdf_server.py    # Main server
mcp-config.json          # Ready-to-use MCP config
tests/                   # Test suite  
scripts/                 # Utilities
cache/                   # PDF cache
mcp_requirements.txt     # Dependencies