mcpField
M
mistral-pdf-to-markdown

mistral-pdf-to-markdown

github.com/fuzhiyuDocuments1050 installsUpdated 47w ago
Repository

About mistral-pdf-to-markdown

A skill that converts PDFs into Markdown with Mistral's OCR API, for readers and researchers who need searchable text or document structure. It can select pages and save embedded images alongside the output.

Key features

  1. 01OCR for scanned PDFs
  2. 02Preserves Markdown structure
  3. 03Extracts embedded images
  4. 04Selects pages or ranges

Use cases

  1. 01Convert research papers to Markdown
  2. 02Extract text from scanned documents
  3. 03Convert selected PDF pages
  4. 04Save figures with Markdown references

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/fuzhiyu/researchprojecttemplate --skill mistral-pdf-to-markdown

After installing, type/mistral-pdf-to-markdownin Claude Code to confirm it loaded.

Bundled filesreference.mdscripts/convert_pdf_to_markdown.py

Details

From the project README

Mistral PDF to Markdown Converter

Convert PDF documents to Markdown format using Mistral's OCR API. Automatically extracts text, formatting, and images.

When to Use

  • Converting research papers or documents to Markdown
  • Extracting text from scanned PDFs (OCR capability)
  • Preserving document structure with headers and formatting
  • Extracting embedded images from PDFs

Quick Start

Use the conversion script from this skill's directory:

# Convert entire PDF
python scripts/convert_pdf_to_markdown.py input.pdf output.md

# Convert specific pages
python scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1-5"
python scripts/convert_pdf_to_markdown.py input.pdf output.md --pages "1,3,5"

Output Structure

Output/PDFConversions/
├── document.md          # Markdown with text and image references
└── images/
    ├── img-0.jpeg      # Extracted images
    ├── img-1.jpeg
    └── ...

Usage in Code

from pathlib import Path
import subprocess

# Run conversion script
result = subprocess.run([
    "python",
    ".claude/skills/mistral-pdf-to-markdown/scripts/convert_pdf_to_markdown.py",
    "input.pdf",
    "Output/PDFConversions/output.md",
    "--pages", "1-10"
], capture_output=True, text=True)

print(result.stdout)

Key Features

  • Markdown formatting: Preserves headers, lists, and structure
  • Image extraction: Saves images to images/ subfolder automatically
  • Page selection: Extract specific pages or ranges
  • Scanned PDF support: True OCR capability for image-based PDFs
  • Relative paths: Image references use ![...](images/img-X.jpeg)

Requirements

The script requires:

  • Mistral API key in Notes/.env (line 2: mistral_api_key=...)
  • Python packages: mistralai, python-dotenv, pypdf

Common Use Cases

Convert Research Paper
python scripts/convert_pdf_to_markdown.py \
  "Data/papers/research.pdf" \
  "Notes/Paper Markdown/research.md"
Extract Specific Sections
# Extract pages 10-20 (introduction and methods)
python scripts/convert_pdf_to_markdown.py \
  "paper.pdf" \
  "Notes/Paper Markdown/intro_methods.md" \
  --pages "10-20"
Extract Figures Only
# Extract pages with figures
python scripts/convert_pdf_to_markdown.py \
  "paper.pdf" \
  "Notes/Paper Markdown/figures.md" \
  --pages "25,27,30,35"

Error Handling

API Key Not Found:

Error: Mistral API key not found in Notes/.env

→ Add mistral_api_key=YOUR_KEY to line 2 of Notes/.env

Page Out of Range:

Warning: Page 100 out of range, skipping

→ Check PDF page count and adjust page selection

API Rate Limit: → Wait a moment and retry, or reduce page count per request

Notes

  • Images are saved as JPEG files in images/ subfolder
  • Markdown image references are automatically updated to images/img-X.jpeg
  • Large PDFs may take longer to process due to API limits
  • For simple text extraction without OCR, consider using the pdf skill instead
  • Scanned PDFs benefit most from this skill's OCR capability

See Also

  • pdf skill - For local PDF manipulation without API calls
  • reference.md - Additional details about the Mistral OCR API

Comments

Markdown supported