carrot-mcp-pdf 0.2.3

Carrot MCP PDF Server

carrot-mcp-pdf

Carrot MCP PDF Server — convert PDFs to structured markdown with optional OCR.

Installation

uv sync --all-packages

Usage

# Run as MCP server
uv run carrot-mcp-pdf

# Or via main CLI
uv run carrot-mcp pdf

# Or as Python module
uv run python -m carrot_mcp_pdf

Tools

Tool	Description
version	Get server version info
get_toc	Get table of contents with page ranges
get_pages	Convert specific pages to markdown. Accepts pages as int (single page), str (range like '1-5,8,10-12'), list, or None. Returns list[TextContent | ImageContent]
grep	Search for exact substring in PDF pages. Case-insensitive by default, or regex. Returns matches with page number, text, and surrounding context.

Architecture

Application Layer (server.py — MCP tools, thin routing)
    ↓ get_toc/get_pages
Conversion Layer (converter.py — pymupdf4llm → markdown + images)
    ↓ force_ocr=True
OCR Layer (ocr.py — litellm vision API)
    ↓ multimodal=False
Cache Layer (cache.py — JSON: %APPDATA%/carrot-mcp/pdf/<md5>.json)

• server.py — MCP tool definitions only, delegates to converter/cache

• converter.py — PDF conversion, image processing, content parsing, VLM config

• ocr.py — Vision model OCR via litellm (single responsibility)

• cache.py — Cache persistence, path management, parse_page_range

• Cache: %APPDATA%/carrot-mcp/pdf/<md5>.json

• Dual format: each page caches both content (images as base64 strings) and ocr_content (OCR text or images)

• Force OCR: PDF-level flag — renders page as image and OCRs it; if VLM not configured, falls back to returning the rendered image

• Image return: images returned as MCP ImageContent attachments (no base64 truncation)

Environment Variables

Variable	Default	Description
CARROT_MCP_MODEL	—	Vision model name for OCR (must be configured if using OCR)
CARROT_MCP_APIKEY	—	API key for the vision model (must be configured if using OCR)
CARROT_MCP_PROXY	—	HTTP proxy URL for API calls
CARROT_MCP_FORCE_MULTIMODAL	—	true = always return images as MCP ImageContent attachments; false = always run OCR. When not set, uses tool parameter. If VLM not configured (no model/apikey), falls back to attachments with warning.

Development

# Run tests
uv run pytest tests/pdf/ -v