Pdf4vllm

io.github.PyJudgePublished by GitHub account PyJudgev1.0.2Updated Oct 24, 2026

PDF reader for vision LLMs. Auto-detects text corruption and switches to image mode.

VerifiedSTDIODesktop onlyWeb Search & ScrapingFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Reads local PDF files and returns their content as ordered text, table, and image blocks, switching to image mode when text is corrupted.

What you can do
A local MCP server that extracts PDF content for vision-capable language models. It offers list_pdfs to find files by glob pattern, read_pdf to return page content as ordered blocks (text, tables, images), and grep_pdf to search text inside PDFs. Extraction modes include auto (try text, fall back to images when corruption is detected), text_only, and image_only. It preserves reading order, limits pages to avoid context overflow, and filters out logos, lines, and headers or footers.
When to use it
Useful when an assistant needs to read local PDFs that may have broken encoding or messy layouts, and you want either clean text or page images depending on quality. Also handy for searching across PDFs or feeding scanned pages to a vision model without exploding token usage.
Requirements
Runs locally as a Python package (pdf4vllm-mcp) via pip or uvx, or from a cloned source directory configured in the client. The grep_pdf tool additionally requires the pdfgrep program installed on the system. No accounts, API keys, or network access are declared; optional settings such as PDF_MAX_PAGES and PDF_PAGE_IMAGE_DPI can be set by environment variable or config.json.
Before you install
The server reads files from the local filesystem, so point it only at directories you are comfortable exposing to the assistant. grep_pdf depends on an external pdfgrep binary. No credentials, payments, or write operations are declared.

Installation

In SourceWeft

  1. Open Pdf4vllm in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

pdf4vllm

[License: MIT] [Python 3.10+] [PyPI] [Open in Gitpod]

PDF reading MCP server optimized for vision LLMs.

한국어

문제

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

해결

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

  • 텍스트 손상 자동 감지 → 이미지로 자동 전환
  • 읽기 순서 보존 (텍스트 → 표 → 이미지 블록 순서대로)
  • 페이지 제한으로 컨텍스트 오버플로우 방지
  • 불필요한 이미지 자동 필터링 (로고, 선, 헤더/푸터)

설치

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

Claude Desktop 설정

bash
git clone https://github.com/PyJudge/pdf4vllm-mcp.gitcd pdf4vllm-mcppython scripts/install_mcp.py

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

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

도구

도구설명
list_pdfsPDF 파일 찾기 (glob 패턴 name_pattern 지원)
read_pdfPDF 내용 블록으로 추출
grep_pdfPDF 내 텍스트 검색 (pdfgrep 설치 필요)

추출 모드

모드설명
auto (기본)텍스트 추출 시도 → 손상 감지 시 이미지로 전환
text_only텍스트/표만 추출, 이미지 없음
image_only페이지를 이미지로만 렌더링

Problem

ApproachIssue
Text extractionEncoding corruption → garbage output, mixed text-image ordering
Image conversionToken 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

bash
pip install pdf4vllm-mcp# or run without installinguvx pdf4vllm-mcp

Claude Desktop Setup

bash
git clone https://github.com/PyJudge/pdf4vllm-mcp.gitcd pdf4vllm-mcppython scripts/install_mcp.py

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

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

Claude Code Setup

Create .mcp.json in your project:

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

Tools

ToolDescription
list_pdfsFind PDF files with glob filtering (name_pattern)
read_pdfExtract PDF content as ordered blocks
grep_pdfSearch text in PDFs using pdfgrep (requires pdfgrep installed)

Extraction Modes

ModeDescription
auto (default)Try text extraction → switch to image if corrupted
text_onlyText/tables only, no images
image_onlyRender pages as images only

Output Format

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

When text is corrupted:

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

Configuration

config.json or environment variables:

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

Test Server

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

License

MIT

GitHub · PyPI

Source: README.md at commit 0ea75c6

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.2LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.