If you’re building a RAG pipeline, an AI assistant, or any workflow where an LLM needs to read real documents, you’ve hit the same wall: your data isn’t clean. It’s an HR Word doc, a supplier PDF, a PowerPoint from last quarter’s planning. None of that is ready for an LLM by default.
Microsoft has an answer for that. MarkItDown is an open-source Python library that converts practically any document format into clean, structured Markdown — the format that LLMs really understand well. It was born inside Microsoft Research as an internal tool for the multi-agent AutoGen framework, released as open-source at the end of 2024, and has since accumulated over 91,000 stars on GitHub. The latest stable version, v0.1.5, came out on February 20, 2026.
Why Markdown for LLMs?
It’s not arbitrary. Markdown occupies an ideal middle ground: it’s close to plain text (low token overhead), but preserves document structure — headings, lists, tables, links. Mainstream models are extensively trained on Markdown and handle it natively. When you send an LLM a raw PDF full of messy whitespace and lost hierarchy, retrieval quality drops. When you send clean Markdown, chunking, embedding, and citations work much better.
MarkItDown’s job is to bridge that gap between messy source material and reliable input for the LLM.
What It Converts
The library handles a wide variety of input formats:
- Office Documents: DOCX, PPTX, XLSX, XLS
- PDFs: via pdfminer (PDFs with text layer; OCR requires the plugin)
- Images: JPG, PNG — with LLM-generated descriptions when you provide a client
- Audio: WAV, MP3 — via speech transcription
- Web Content: HTML, URLs
- Structured Data: CSV, JSON, XML
- Compressed Files: ZIP (processes content recursively)
The architecture is clean: each format has a dedicated DocumentConverter class, registered on startup. Processing happens entirely in memory — no temporary files — which matters both for performance and security.
How to Install MarkItDown? (in 4 lines)
pip install 'markitdown[all]'
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("informe_q4.xlsx")
print(result.text_content)
That’s it. result.text_content returns structured Markdown, preserving sheet names, table rows, and any headings.
How to Use MarkItDown from the Command Line?
MarkItDown also comes as a command-line tool, useful for batch preprocessing:
# Convert a single file
markitdown documento.pdf -o output.md
# Convert and pipe to another tool
markitdown reporte.docx | grep "## "
Image Description with an LLM Client
For images (and audio), MarkItDown can call an LLM to generate a description — useful when you need images within a document to be semantically searchable:
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("diagrama_arquitectura.png")
print(result.text_content)
# Returns a structured description of the image content
This works with any OpenAI-compatible client — you’re not locked into OpenAI specifically.
The OCR Plugin
For PDFs and Office files containing images with embedded text, the markitdown-ocr plugin extends the base library with LLM Vision-based OCR:
pip install 'markitdown[all]' markitdown-ocr
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(
enable_plugins=True,
llm_client=OpenAI(),
llm_model="gpt-4o",
)
result = md.convert("contrato_escaneado.pdf")
print(result.text_content)
If no llm_client is provided, the plugin loads but silently falls back to the standard text extractor.
How to Connect MarkItDown to Claude? (step by step)
One of the most interesting additions in the v0.1.x cycle: MarkItDown now comes with an official MCP server (markitdown-mcp), which means you can expose document conversion as a tool within Claude Desktop or any MCP-compatible client.
In practice: instead of manually preprocessing files before sending them to Claude, your MCP setup handles the conversion on the fly. Claude can call MarkItDown, get structured Markdown back, and reason about the content without you manually managing the pipeline step.
1. Install the MCP server
pip install markitdown-mcp
Test it directly from the terminal — uses STDIO by default:
markitdown-mcp
2. For Claude Desktop, Microsoft recommends the Docker image
Build the image from the MarkItDown repo:
docker build -t markitdown-mcp:latest .
And add this entry to your claude_desktop_config.json:
{
"mcpServers": {
"markitdown": {
"command": "docker",
"args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
}
}
}
3. If you need to convert local files, mount the directory to the container:
docker run -it --rm -v /home/usuario/data:/workdir markitdown-mcp:latest
Everything in data becomes accessible as /workdir/arquivo.pdf inside the container.
The server exposes a single tool: convert_to_markdown(uri), which accepts http:, https:, file:, and data: URIs.
markitdown-mcpis designed for local use with trusted agents. By default it binds tolocalhostand isn’t exposed to the network. Don’t bind it to other interfaces without understanding the security implications.
Where MarkItDown Fits (and Where It Doesn’t)
MarkItDown is the right tool when you need fast, lightweight conversion for LLM consumption — RAG pipelines, document indexing, AI assistants that need to read business files.
It’s not the right tool when:
- You need high-fidelity formatting for human readers → use Pandoc instead
- Your documents are complex scientific PDFs with tables, equations, and reading order challenges → Docling (IBM) handles those better
- You’re building a large-scale document ETL pipeline with 40+ connectors → Unstructured.io is more appropriate there
Knowing where each tool ends is as useful as knowing what it does.
v0.1.5: What Changed
The latest version (February 20, 2026) addressed two security dependencies:
- Updates
mammothto 1.11.0 to resolve CVE-2025-11849 - Updates
pdfminer.sixto 20251107 to resolve GHSA-wf5f-4jwr-ppcp
Also in recent versions: switched from minidom to defusedxml for XML parsing — another security hardening move. If you’re running an older version of MarkItDown in any environment processing untrusted documents, it’s worth updating.
The Practical Conclusion
The preprocessing step in AI pipelines is boring, but it’s where a lot of quality is won or lost. MarkItDown is a well-maintained library, MIT-licensed, from a team that built it for real production use inside one of the world’s largest AI research groups. It handles the messy conversion layer so you can focus on what the LLM does with the data.
Install it, point it at your document pile, and send your LLM something it can actually work with.
pip install 'markitdown[all]'
GitHub: microsoft/markitdown
How are you handling document preprocessing in your AI projects? Are you building something custom or relying on libraries like this? Share your experience in the comments 