Skip to content
JournalTORIS / FIELD NOTES

← BlogDeveloper tools

MarkItDown Guide: Convert PDFs & Office Docs to Markdown + MCP

How to use Microsoft's open-source MarkItDown for LLM-ready Markdown conversion, OCR plugins, markitdown-mcp setup, and secure deployment.

#MarkItDown #Markdown #MCP #LLM #PDF #OpenSource

Read the Korean original

MarkItDown Guide: Convert PDFs & Office Docs to Markdown + MCP

Q. Why convert PDF, PowerPoint, and Excel files to Markdown before feeding them to an AI agent? Modern LLMs such as GPT-4o are trained on vast amounts of Markdown and understand headings, lists, and tables natively. Microsoft's open-source MarkItDown converts office documents and PDFs into token-efficient Markdown so RAG and agent pipelines can parse structure accurately.

⚠️ Accuracy guardrail: This guide was written on November 21, 2026 based on the official microsoft/markitdown GitHub repository (API and README) and the v0.1.9 release notes (published October 21, 2026). Star/fork counts and supported extras may change in future releases, and cloud features such as Azure Document Intelligence, Azure Content Understanding, image captioning, and speech transcription are subject to separate service pricing.

30-second summary

  • Massive adoption: An MIT-licensed Python utility maintained by Microsoft, with 197,251 GitHub stars, 14,935 forks, and latest release v0.1.9 as of November 21, 2026.
  • Broad format support: Handles PDF, PowerPoint, Word, Excel, HTML, CSV, JSON, XML, ZIP archives, EPub, image EXIF/captioning, audio transcription, and YouTube transcript URLs.
  • Lightweight local core: Built-in converters run locally without cloud billing, and optional extras like [pdf, docx, pptx] let you install only what you need.
  • MCP and OCR extensions: Pair markitdown-mcp with Claude Desktop or Cursor to expose convert_to_markdown(uri), and enable markitdown-ocr to extract text from embedded images via LLM Vision.

MarkItDown conversion pipeline diagram

Why MarkItDown instead of plain text extraction

The biggest loss when extracting text for LLMs is broken tables and flattened heading hierarchy. While older tools like textract dump raw text streams, MarkItDown preserves headings (#), lists (-), tables (|), and links ([text](url)) as structured Markdown.

Its output is designed for text analysis pipelines rather than high-fidelity human print layouts, keeping token consumption compact. If Firecrawl & Firecrawl Local handles crawling live websites into Markdown, MarkItDown fills the other half of the workflow for PDFs and office documents already sitting on your disk.

MarkItDown developer workspace photo

Advertisement

Installation and modular optional dependencies

On Python 3.10 through 3.14, you can set up a virtual environment and install everything in one command. Use [all] for full coverage or specify only the formats your pipeline needs.

python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'

Common optional dependency groups include:

Extra option Enabled capability Notes
[all] All optional dependencies Quickest for local testing
[pdf, docx, pptx] PDF, Word, PowerPoint Core document RAG stack
[xlsx, xls] Modern and legacy Excel Spreadsheet table extraction
[outlook] Outlook .msg files Internal email archives
[audio-transcription] .wav and .mp3 transcription Relies on hosted service
[youtube-transcription] YouTube transcript fetching Accepts YouTube URLs
[az-doc-intel] / [az-content-understanding] Azure layout & multimodal extraction Billable Azure API calls

The CLI supports output redirection (>), -o, and standard input piping (|).

markitdown report.pdf -o report.md
cat report.pdf | markitdown

Python API, OCR plugin, and Azure integration

In Python, converting a file takes two lines via MarkItDown().convert(). For image files or PowerPoint slides, you can pass an OpenAI-compatible llm_client and llm_model to generate visual descriptions.

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("quarterly_plan.xlsx")
print(result.markdown)

For scanned PDFs or image-heavy documents, the third-party markitdown-ocr plugin adds LLM-based OCR across PDF, DOCX, PPTX, and XLSX converters. Because plugins are disabled by default for safety, you must explicitly pass --use-plugins in the CLI or enable_plugins=True in Python alongside llm_client.

When local parsers fall short on complex multi-column tables or when you need structured YAML front matter and video/audio analysis, MarkItDown can route requests to Azure Document Intelligence (-d / --use-docintel) or Azure Content Understanding (--use-cu).

Capability Built-in converters Azure Document Intelligence Azure Content Understanding
Conversion engine Offline format-specific parsers Cloud layout extraction Cloud multimodal extraction
Structured fields Not available YAML front matter from model/query fields YAML front matter from analyzer fields
Audio & video Basic audio only, no video Not supported Audio and video analyzers
Cost Local compute (free) Billable Azure API calls Billable Azure API calls

Microsoft MarkItDown official GitHub repository

Connecting Claude Desktop and Cursor with markitdown-mcp

To let AI coding agents convert files and URLs on demand, use the markitdown-mcp package. It supports STDIO, Streamable HTTP, and SSE transports and exposes a single convert_to_markdown(uri) tool accepting http:, https:, file:, and data: URIs.

pip install markitdown-mcp
# Default STDIO mode
markitdown-mcp
# Streamable HTTP / SSE on localhost
markitdown-mcp --http --host 127.0.0.1 --port 3001

For Claude Desktop, the official documentation recommends running markitdown-mcp inside Docker and mounting only the directory you want the agent to access (/workdir).

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/home/user/data:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}

Security considerations: narrow the I/O surface

Q. Is it safe to expose convert() or markitdown-mcp directly on a public web server? No. MarkItDown executes I/O with the privileges of the host process, and markitdown-mcp provides no built-in authentication.

The official security guidance recommends calling the narrowest conversion method for your use case. If your service only handles local files, call convert_local() instead of the permissive convert(). For remote URLs in server-side apps, fetch and validate targets yourself—blocking private, loopback, link-local, and cloud metadata IPs—and pass the result to convert_response() or convert_stream(). Keep in mind that image captioning and audio transcription rely on web-hosted services, so omit those extras in strict offline environments.

Toris's take

If your bottleneck is turning PDFs, slide decks, and spreadsheets into clean LLM context, MarkItDown is an easy day-one win. Running markitdown-mcp inside a scoped Docker container for Claude Desktop or Cursor immediately eliminates manual copy-pasting and token bloat.

On the other hand, if you need JavaScript-rendered web scraping or full-site mapping, Firecrawl Local is a better fit. Combining both gives your agents a clean Markdown ingestion layer for both web and local documents. For automation or engineering inquiries, visit Toris Services.

Sources

Advertisement