pdf-reader MCP server

An MCP server for reading PDFs

Components

Resources

The server provides academic-aware PDF resources with:

• Custom file:// URI scheme for accessing individual PDFs
• Academic structure detection and key section extraction
• Metadata enriched with document type classification
• Resources optimized for agent understanding

Academic Prompts

The server provides specialized academic analysis prompts:

• summarize-academic-paper: Intelligent academic paper summarization
  • Required "file_path" argument for PDF location
  • Optional "focus" argument (general/methodology/results/implications)
  • Generates prompts with key sections, citations, and metadata
• analyze-research-methodology: Deep methodology analysis
  • Required "file_path" argument for PDF location
  • Focuses on research design, data collection, and statistical methods

Enhanced Tools

Basic PDF Processing:

• load-pdf: Load and cache a PDF file for processing
• get-metadata: Get PDF metadata and document information
• extract-images: Extract embedded images with metadata
• render-page: Render PDF pages as high-resolution images

Academic Enhancements:

• extract-academic-text: Text extraction with proper reading order and math formula preservation
• detect-sections: Identify academic sections (Abstract, Introduction, Methods, Results, etc.)
• extract-abstract: Specifically extract the abstract section
• extract-key-sections: Get key sections optimized for agent understanding
• extract-citations: Parse in-text citations and reference lists
• chunk-content: Break content into agent-friendly semantic chunks
• analyze-document-structure: Comprehensive academic document analysis

Configuration

This PDF reader MCP server provides comprehensive PDF processing capabilities including:

• Full text extraction from any PDF
• High-resolution image extraction
• Table detection and extraction
• Annotation and comment extraction
• PDF metadata retrieval
• Page rendering to images
• Document structure analysis

Installation & Setup

Prerequisites

• Python 3.13 or higher
• uv package manager (install with pip install uv)

Install Dependencies

uv sync

IDE Integration

VSCode with MCP Extension

1. Install the MCP VSCode Extension
2. Open your VSCode settings (.vscode/settings.json) and add:

{
  "mcp.servers": {
    "pdf-reader": {
      "url": "http://localhost:8000/sse",
      "description": "PDF reader with full extraction capabilities"
    }
  }
}

WindSurf IDE

1. Open WindSurf settings
2. Navigate to Extensions → MCP Servers
3. Add a new server configuration:

{
  "name": "pdf-reader",
  "url": "http://localhost:8000/sse",
  "description": "Comprehensive PDF processing server"
}

Cursor IDE

1. Open Cursor settings (Cmd/Ctrl + ,)
2. Search for "MCP" or navigate to Extensions → MCP
3. Add server configuration:

{
  "mcpServers": {
    "pdf-reader": {
      "url": "http://localhost:8000/sse",
      "description": "PDF reader with text, image, and table extraction"
    }
  }
}

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pdf-reader": {
      "url": "http://localhost:8000/sse",
      "description": "PDF reader with comprehensive extraction capabilities"
    }
  }
}

Starting the Server

Before using the PDF reader in any IDE, start the HTTP server:

# Navigate to the pdf-reader directory
cd /path/to/your/pdf-reader

# Start the server
uv run pdf-reader

The server will start on http://localhost:8000 with the MCP SSE endpoint available at /sse for all IDEs to connect to.

Usage Examples

Once configured in your IDE, you can use the PDF reader with natural language commands:

Basic PDF Processing

"Load the research paper at /path/to/paper.pdf and extract all the text"
"Get metadata for the PDF document at /documents/report.pdf"
"Extract all images from the PDF on page 3"

Advanced Analysis

"Summarize the PDF document in technical style focusing on methodology"
"Analyze the structure of this PDF and tell me about its organization"
"Extract all tables from the document and show me the data"

Visual Processing

"Render page 5 of the PDF as a high-resolution image"
"Extract all annotations and comments from this PDF"
"Show me all the images embedded in this document"

Available Tools

Tool	Description	Parameters
load-pdf	Load and cache PDF	file_path, optional name
extract-text	Extract text content	file_path, optional page
extract-images	Extract embedded images	file_path, optional page
get-metadata	Get document metadata	file_path
extract-tables	Extract table data	file_path, optional page
extract-annotations	Extract comments/highlights	file_path
render-page	Render page as image	file_path, page, optional dpi

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /Users/cloudchase/Desktop/AverageJoesLab/mcp-servers/pdf-reader run pdf-reader

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.