pdf4vllm
PDF reader for vision LLMs. Auto-detects text corruption and switches to image mode.
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"pdf4vllm-mcp": {
"args": [
"pdf4vllm-mcp@1.0.2"
],
"command": "uvx"
}
}
}可用工具 （5 个）
该服务在 MCP 协议中暴露的工具，AI 可按需调用
tavily_search 14 个参数 需填 1 项
Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.
必填参数：query
tavily_extract 6 个参数 需填 1 项
Extract content from URLs. Returns raw page content in markdown or text format.
必填参数：urls
tavily_crawl 11 个参数 需填 1 项
Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.
必填参数：url
tavily_map 8 个参数 需填 1 项
Map a website's structure. Returns a list of URLs found starting from the base URL.
必填参数：url
tavily_research 2 个参数 需填 1 项
Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings.
必填参数：input
服务介绍
pdf4vllm
[
PDF reading MCP server optimized for vision LLMs.
<!- - mcp-name: io.github.PyJudge/pdf4vllm - ->
# 문제
| 방식 | 문제점 |
|- -- -- -|- -- -- -- -|
| 텍스트 추출 | 인코딩 깨짐 → 쓰레기 출력, 이미지-텍스트 순서 뒤섞임 |
| 이미지 변환 | 토큰 폭발 (특히 페이지 많을 때) |
# 해결
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
