Microsoft MarkItDown converts common file formats into Markdown for reading and downstream AI work. It is a practical first step for turning a report into text without building a document pipeline. Check the output before summarizing: successful conversion can still produce empty text or misleading table structure.
Install and choose a working environment
Tool version 0.1.9. Documentation checked 2026-11-16. The upstream source snapshot and installed package are pinned separately; the snapshot is not claimed to be the package’s release commit.
Create a project virtual environment first (python -m venv .venv), activate it using your shell’s normal procedure, and run the install command in that environment. The recorded Python tests used Linux/Python 3.12; other operating systems were not locally validated.
python -m pip install "markitdown[pdf,docx]==0.1.9"
markitdown --help
markitdown report.pdf -o report.md
This package is a CLI/Python library, not an MCP server configured by the install command above. Run the examples in the project’s environment and give the resulting files to your assistant.
- Claude Code: open the project, ask it to inspect the saved script/output, and confirm the interpreter path before execution.
- Codex: open the same workspace, provide the script/output filename, and ask for a review or a locally permitted run.
- Cursor: choose the project’s Python interpreter, run the command in its terminal, then attach the resulting file in chat.
These are file/terminal workflows, not a claim of a vendor-specific integration. The three client interfaces were not tested locally.
Three practical uses
1. Convert a text PDF
markitdown report.pdf -o report.md
Expected: Open report.md and compare headings, key values and paragraphs with the PDF.
2. Convert meeting notes
markitdown meeting.docx -o meeting.md
Expected: Inspect meeting.md, especially column labels and any embedded tables.
3. Prepare a grounded summary
Read meeting.md. List decisions, owners and deadlines with supporting quotes. Mark absent fields as not provided, and flag possible conversion errors first.
Expected: a response that follows the stated scope and exposes the requested source or tool result. Verify those references before acting.
What our tests established
In the 0.1.9 isolated run, a text PDF retained its sentence while a PDF without a text layer returned success with effectively empty output. The HTML table retained headers; the DOCX fixture placed labels in a data row. OCR, Azure and other formats were not tested.
Tests were run by Codex on synthetic data; no claim of the owner personally testing or reviewing this guide. Examples added above are documentation-based unless included in that recorded scope.
Common errors and fixes
Conversion succeeds with empty text
Check whether the PDF has selectable text. Use a separate OCR workflow when needed and reject empty output.
DOCX headers appear as data
Compare the Word table settings and output. Use a structured parser when downstream code depends on headers.
Missing converter dependency
Install the documented extras for your format and run the CLI from that same Python environment.
Limits, costs and license
MIT licensed. This local conversion path needs no model API. Optional cloud or model features have separate credentials, data handling and fees. Markdown is not a reconstruction of the original layout.
When to choose an alternative
-
When you need document structure and table metadata:Docling。
-
For a PDF-specific Python API:PyMuPDF4LLM。
FAQ
Is MarkItDown from Microsoft?
Yes; this guide covers the official microsoft/markitdown project.
Is MarkItDown itself an MCP server?
This page uses the core CLI. An MCP wrapper is a separate installation and integration path.
Can I convert files without uploading them?
Yes, the basic conversion shown is local. Optional API-backed features have different data handling.
Official sources
If table structure matters to downstream code, compare Docling's table preservation. For PDF input, also see PyMuPDF4LLM's parsing workflow.