Skip to main content
Glama

pdf4vllm

License: MIT Python 3.10+ PyPI Open in Gitpod

PDF reading MCP server optimized for vision LLMs.

문제

방식

문제점

텍스트 추출

인코딩 깨짐 → 쓰레기 출력, 이미지-텍스트 순서 뒤섞임

이미지 변환

토큰 폭발 (특히 페이지 많을 때)

Related MCP server: PDF MCP Server

해결

pdf4vllm은 PDF가 지저분하다고 가정합니다.

  • 텍스트 손상 자동 감지 → 이미지로 자동 전환

  • 읽기 순서 보존 (텍스트 → 표 → 이미지 블록 순서대로)

  • 페이지 제한으로 컨텍스트 오버플로우 방지

  • 불필요한 이미지 자동 필터링 (로고, 선, 헤더/푸터)

설치

pip install pdf4vllm-mcp
# 또는
uvx pdf4vllm-mcp

Claude Desktop 설정

git clone https://github.com/PyJudge/pdf4vllm-mcp.git
cd pdf4vllm-mcp
python scripts/install_mcp.py

또는 직접 설정 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pdf4vllm": {
      "command": "/python/경로",
      "args": ["/pdf4vllm-mcp/경로/src/server.py"]
    }
  }
}

도구

도구

설명

list_pdfs

PDF 파일 찾기 (glob 패턴 name_pattern 지원)

read_pdf

PDF 내용 블록으로 추출

grep_pdf

PDF 내 텍스트 검색 (pdfgrep 설치 필요)

추출 모드

모드

설명

auto (기본)

텍스트 추출 시도 → 손상 감지 시 이미지로 전환

text_only

텍스트/표만 추출, 이미지 없음

image_only

페이지를 이미지로만 렌더링


Problem

Approach

Issue

Text extraction

Encoding corruption → garbage output, mixed text-image ordering

Image conversion

Token explosion (especially with many pages)

Solution

pdf4vllm assumes PDFs are messy.

  • Auto-detects text corruption → switches to image automatically

  • Preserves reading order (text → table → image blocks in sequence)

  • Page limits prevent context overflow

  • Filters unnecessary images (logos, lines, headers/footers)

PDF Input
    ↓
Corruption Detection (pdfminer.six + pattern analysis)
    ↓
┌─────────────┬─────────────┐
│  Corrupted  │    Clean    │
│  → Image    │  → Text +   │
│    only     │    Tables + │
│             │    Images   │
└─────────────┴─────────────┘
    ↓
Ordered Blocks (JSON)

Install

pip install pdf4vllm-mcp
# or run without installing
uvx pdf4vllm-mcp

Claude Desktop Setup

git clone https://github.com/PyJudge/pdf4vllm-mcp.git
cd pdf4vllm-mcp
python scripts/install_mcp.py

Or manually edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pdf4vllm": {
      "command": "/path/to/python",
      "args": ["/path/to/pdf4vllm-mcp/src/server.py"]
    }
  }
}

Claude Code Setup

Create .mcp.json in your project:

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

Tools

Tool

Description

list_pdfs

Find PDF files with glob filtering (name_pattern)

read_pdf

Extract PDF content as ordered blocks

grep_pdf

Search text in PDFs using pdfgrep (requires pdfgrep installed)

Extraction Modes

Mode

Description

auto (default)

Try text extraction → switch to image if corrupted

text_only

Text/tables only, no images

image_only

Render pages as images only

Output Format

{
  "pages": [
    {
      "page_number": 1,
      "content_blocks": [
        {"type": "text", "content": "..."},
        {"type": "table", "content": "| A | B |"},
        {"type": "image", "content": "[IMAGE_0]"}
      ]
    }
  ]
}

When text is corrupted:

{
  "page_number": 2,
  "content_blocks": [],
  "text_corrupted": true,
  "page_image": "[IMAGE_1]"
}

Configuration

config.json or environment variables:

{
  "max_pages_per_request": 10,
  "max_image_dimension": 842,
  "page_image_dpi": 100
}
export PDF_MAX_PAGES=20
export PDF_PAGE_IMAGE_DPI=150

Test Server

pip install pdf4vllm-mcp[test]
python test_server.py
# → http://localhost:8000

License

MIT


GitHub · PyPI

Available Tools

3 tools
grep_pdfA

Search text in PDFs. Standard grep/rg does NOT work on PDFs (binary format). Use this tool instead. Returns matching lines with page numbers. NOTE: No page limit (unlike read_pdf's 10-page limit).

Inputs: pattern (required), file_path, working_directory, ignore_case, +6 more.

list_pdfsA

Find PDF files in a directory. Use name_pattern for glob filtering (e.g., 'report'). Returns name, path, pages for each PDF. Use the returned 'path' directly with read_pdf.

Inputs: working_directory, recursive, max_depth, name_pattern.

read_pdfA

Read PDF content. Always prefer this over cat or file read for PDF files. Limits: 10 pages per request. Works with both text and scanned documents. Use 'image_only' to see actual page layout, or 'text_only' for pure text.

Inputs: file_path (required), start_page, end_page, extraction_mode, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: grep_pdf searches text within PDFs, list_pdfs finds PDF files in directories, and read_pdf extracts content from PDFs. There is no overlap in functionality, making it easy for an agent to select the correct tool without confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (grep_pdf, list_pdfs, read_pdf). The naming is predictable and readable, with no deviations or mixed conventions, ensuring clarity and ease of use.

    Tool Count5/5

    With 3 tools, the server is well-scoped for its purpose of PDF processing. Each tool earns its place by covering essential operations: listing, reading, and searching PDFs, without being overly sparse or bloated.

    Completeness4/5

    The tool set covers core PDF operations (list, read, search) effectively, with no dead ends. A minor gap exists in lacking explicit CRUD operations like create or delete PDFs, but this is reasonable given the server's focus on reading and searching rather than full lifecycle management.

    Related MCP Connectors

    Related MCP Servers