PDF Inline Image RAG

An MCP server and CLI for building local, searchable SQLite databases from PDFs where important content appears inside inline images, figures, diagrams, or scanned image blocks.

The key rule is simple:

• Extract PDF text normally.
• Extract only actual PDF image blocks, not whole-page screenshots.
• Insert image placeholders into the page text stream at their page-flow location.
• Store every extracted image with its exact PDF bounding box.

Example text_with_images marker:

[[IMAGE page=72 index=1 bbox=80.6,76.0,535.7,645.7 size=1896x2373 file=mtp-2_assets/images/page_0072_image_01.png]]

This gives an AI agent enough context to search normal text, notice where an image appeared, fetch the image asset, caption/OCR it, and save the caption back into the searchable index.

Install

pip install git+https://github.com/Joncallim/pdf-inline-image-rag-mcp.git

For local development:

git clone https://github.com/Joncallim/pdf-inline-image-rag-mcp.git
cd pdf-inline-image-rag-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

MCP Usage

Add this server to your MCP client:

{
  "mcpServers": {
    "pdf-inline-image-rag": {
      "command": "pdf-inline-image-rag-mcp"
    }
  }
}

Available tools:

• build_pdf_rag
• search_pdf_rag
• get_pdf_page
• get_pdf_image
• list_uncaptioned_pdf_images
• save_pdf_image_caption
• inspect_pdf_rag

Typical flow:

1. Call build_pdf_rag with a PDF path and output directory.
2. Call search_pdf_rag for normal text queries.
3. When a result includes [[IMAGE ...]], call get_pdf_page or get_pdf_image.
4. Caption or OCR the image with your preferred model.
5. Call save_pdf_image_caption so the caption is added to page text and FTS.

CLI Usage

Build a database:

pdf-inline-image-rag build \
  --input /path/to/file.pdf \
  --output-dir outputs/pdf_rag \
  --replace

Build only selected pages:

pdf-inline-image-rag build \
  --input /path/to/file.pdf \
  --output-dir outputs/pdf_rag \
  --pages 1-10,42

Search:

pdf-inline-image-rag search \
  --db outputs/pdf_rag/file_rag.sqlite \
  "sector method"

Inspect:

pdf-inline-image-rag inspect \
  --db outputs/pdf_rag/file_rag.sqlite

Output Layout

outputs/pdf_rag/
  file_rag.sqlite
  file_rag_export.md
  file_assets/
    images/page_0001_image_01.png
    visual_json/page_0001.visual.json

Whole-page PNG rendering is disabled by default. Use --render-pages only for debugging.

SQLite Tables

pages:

• text: normal embedded PDF text
• text_with_images: text plus inline image placeholders
• markdown: page-level retrieval document
• image_count
• needs_ocr

images:

• file_path
• bbox_x0, bbox_y0, bbox_x1, bbox_y1
• width, height
• block_number
• placeholder
• caption
• caption_model

pages_fts:

• FTS5 index over text, image placeholders, markdown, and saved captions.

Notes

This project does not invent image captions. It extracts image blocks and makes them discoverable. Use an OCR or vision model to caption the extracted images, then persist the caption with save_pdf_image_caption.