pdf-mcp 馃搫

Production-ready MCP server for PDF processing with intelligent caching.

A Python implementation of the Model Context Protocol (MCP) server that enables AI agents like Claude to read, search, and extract content from PDF files efficiently.

mcp-name: io.github.jztan/pdf-mcp

鉁� Features

• 馃殌 8 Specialized Tools - Purpose-built tools for different PDF operations
• 馃捑 SQLite Caching - Persistent cache survives server restarts (essential for STDIO transport)
• 馃搫 Smart Pagination - Read large PDFs in manageable chunks
• 馃攳 Full-Text Search - Find content without loading entire document
• 馃柤锔� Image Extraction - Extract images as base64 PNG
• 馃寪 URL Support - Read PDFs from HTTP/HTTPS URLs
• 鈿� Fast Subsequent Access - Cached pages load instantly

馃摝 Installation

pip install pdf-mcp

馃殌 Quick Start

claude mcp add pdf-mcp -- pdf-mcp

Or add to ~/.claude.json:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

Location of config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%Claudeclaude_desktop_config.json

After updating the config, restart Claude Desktop to load the MCP server.

VS Code has built-in MCP support via GitHub Copilot (requires VS Code 1.102+).

Using CLI (Quickest):

code --add-mcp '{"name":"pdf-mcp","command":"pdf-mcp"}'

Using Command Palette:

1. Open Command Palette (Cmd/Ctrl+Shift+P)
2. Run MCP: Open User Configuration (for global) or MCP: Open Workspace Folder Configuration (for project-specific)
3. Add the configuration:

   {
     "servers": {
       "pdf-mcp": {
         "command": "pdf-mcp"
       }
     }
   }
   

4. Save the file. VS Code will automatically load the MCP server.

Manual Configuration:
Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

Add to Codex CLI using the command:

codex mcp add pdf-mcp -- pdf-mcp

Or configure manually in ~/.codex/config.toml:

[mcp_servers.pdf-mcp]
command = "pdf-mcp"

Create or edit .kiro/settings/mcp.json in your workspace:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp",
      "args": [],
      "disabled": false
    }
  }
}

Save the file and restart Kiro. The PDF tools will appear in the MCP panel.

Most MCP clients use a standard configuration format:

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

If using uvx (recommended for isolated environments):

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

Testing Your Setup

# Verify pdf-mcp is installed and working
pdf-mcp --help

馃洜锔� Tools

1. pdf_info - Get Document Information

Always call this first to understand the document before reading.

"Read the PDF at /path/to/document.pdf"

Returns: page count, metadata, table of contents, file size, estimated tokens.

2. pdf_read_pages - Read Specific Pages

Read pages in chunks to manage context size.

"Read pages 1-10 of the PDF"
"Read pages 15, 20, and 25-30"

3. pdf_read_all - Read Entire Document

For small documents only (has safety limit).

"Read the entire PDF (it's only 10 pages)"

4. pdf_search - Search Within PDF

Find relevant pages before loading content.

"Search for 'quarterly revenue' in the PDF"

5. pdf_get_toc - Get Table of Contents

"Show me the table of contents"

6. pdf_extract_images - Extract Images

"Extract images from pages 1-5"

7. pdf_cache_stats - View Cache Statistics

"Show PDF cache statistics"

8. pdf_cache_clear - Clear Cache

"Clear expired PDF cache entries"

馃搵 Example Workflow

For a large document (e.g., 200-page annual report):

User: "Summarize the risk factors in this annual report"

Claude's workflow:
1. pdf_info("report.pdf") 
   鈫� Learns: 200 pages, TOC shows "Risk Factors" on page 89

2. pdf_search("report.pdf", "risk factors")
   鈫� Finds relevant pages: 89-110

3. pdf_read_pages("report.pdf", "89-100")
   鈫� Reads first batch

4. pdf_read_pages("report.pdf", "101-110")
   鈫� Reads second batch

5. Synthesizes answer from chunks

馃捑 Caching

The server uses SQLite for persistent caching because MCP with STDIO transport spawns a new process for each conversation.

Cache Location

• ~/.cache/pdf-mcp/cache.db

What's Cached

Cache Invalidation

• Automatic when file modification time changes
• Manual via pdf_cache_clear tool
• TTL: 24 hours (configurable)

鈿欙笍 Configuration

Environment variables:

# Cache directory (default: ~/.cache/pdf-mcp)
PDF_MCP_CACHE_DIR=/path/to/cache

# Cache TTL in hours (default: 24)
PDF_MCP_CACHE_TTL=48

馃敡 Development

# Clone
git clone https://github.com/jztan/pdf-mcp.git
cd pdf-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Type checking
mypy src/

# Linting
ruff check src/

馃搳 Comparison

馃 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

馃搫 License

MIT License - see LICENSE file.

馃敆 Links

• PyPI Package
• MCP Documentation
• GitHub Repository
• Blog Post: How I Built pdf-mcp