pdf4vllm

PDF reading MCP server optimized for vision LLMs.

한국어

문제

방식	문제점
텍스트 추출	인코딩 깨짐 → 쓰레기 출력, 이미지-텍스트 순서 뒤섞임
이미지 변환	토큰 폭발 (특히 페이지 많을 때)

해결

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

Metadata

Release files for pdf4vllm-mcp 1.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pdf4vllm-mcp 1.1.3
File	Size	Uploaded
pdf4vllm_mcp-1.1.3.tar.gz	28.5 kB	Jan 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pdf4vllm-mcp 1.1.3
File	Interpreter	ABI	Platform	Reset
pdf4vllm_mcp-1.1.3-py3-none-any.whl 31.5 kB Jan 12, 2026	Python 3	none	any	Details

Total release size: 60.0 kB

Release files / pdf4vllm_mcp-1.1.3.tar.gz

Download URL	pdf4vllm_mcp-1.1.3.tar.gz
Size	28.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`cf58a22cf953b76fb1cba2c043e9e14fd3d5c68fb3000006a5b3cccd11b4b268`
BLAKE2b-256 checksum How to use checksums	`28617d52f290a5137cc611ca752a15250b0aca7fba3c8a68898f152af3d9704c`
Upload date	Jan 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.9`

Release files / pdf4vllm_mcp-1.1.3-py3-none-any.whl

Download URL	pdf4vllm_mcp-1.1.3-py3-none-any.whl
Size	31.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`921e1272541a2d5ef4283416bc4c3dc401761b75ec4b8fe4dc3b57c0649259cd`
BLAKE2b-256 checksum How to use checksums	`1f3b29667906d94e504dd20b2f7aa200db48558f509778ec3c7fa204da90b2a3`
Upload date	Jan 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.9`