About pdf4vllm
pdf4vllm is a PDF-reading MCP server optimized for vision LLMs, for workflows that need to extract PDF content while handling corrupted text and context limits. It detects text corruption and switches to image mode, while preserving the order of text, tables, and image blocks.
Key features
- 01Detect corrupted text and switch to image mode
- 02Extract text, tables, and images in reading order
- 03Limit pages to avoid context overflow
- 04Filter logos, lines, headers, and footers
- 05Find, read, and search PDFs
Use cases
- 01Read PDFs whose extracted text is corrupted
- 02Process long PDFs with page limits
- 03Search for text within PDFs
MCP support
pdf4vllm exposes `list_pdfs`, `read_pdf`, and `grep_pdf` tools for MCP clients to find, read, and search PDFs.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEpdf4vllm
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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.