MarkItDown

What it is

MarkItDown is a lightweight Python utility from Microsoft that converts files to Markdown for LLMs and text analysis pipelines. Its README says it tries to keep the structure that matters, including headings, lists, tables and links. The output is meant for text analysis tools. The README warns it may not be the best option when a person needs a high-fidelity copy. You run it as a command, from Python, or as an MCP server that an agent calls.

1. You point it at a file, a web address or a stream
2. The converter for that format reads it
3. Headings, lists, tables and links become Markdown
4. You save the text or pass it to your LLM

Who it suits

Developers who feed documents to an LLM or a search index, and anyone who wants the text of Office files without writing a parser for each format. Skip it if you need a faithful copy for people to read.

Where to use it

The maker documents these routes, and the kit has a page for each.

• The command line: the markitdown command, installed with pip
• Python: the MarkItDown class, with convert(), convert_local() and convert_stream()
• An MCP server: markitdown-mcp over STDIO, Streamable HTTP or SSE, with steps for Claude Desktop
• Docker: an image built from the repository’s Dockerfile, fed through standard input
• Azure: Document Intelligence or Content Understanding for cloud conversion
• Plugins: third-party converters, and one that reads text inside images with an LLM

The README lists PDF, PowerPoint, Word, Excel, images, audio, HTML, CSV, JSON, XML, ZIP files, YouTube URLs and EPubs as inputs, and adds “and more”.

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with a page for each route above. The main route is pip, inside a virtual environment.

1. Make a virtual environment and activate it.
2. Install the package with every optional format.
3. Run it on one file and read the result.

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

To install only some formats, name them. This line installs the PDF, Word and PowerPoint dependencies.

pip install 'markitdown[pdf, docx, pptx]'

How to use it

Give the command a file. It writes Markdown to standard output, or to the file you name with -o. It also reads from a pipe.

markitdown path-to-file.pdf > document.md
markitdown path-to-file.pdf -o document.md
cat path-to-file.pdf | markitdown

In Python, the same conversion takes four lines.

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.markdown)

Example

You have a slide deck, deck.pptx, and want an LLM to answer questions about it. With the package installed, you run this:

markitdown deck.pptx -o deck.md

Open deck.md. The README says MarkItDown aims to preserve structure such as headings, lists, tables and links, so the text is ready to paste into a chat or an index. For descriptions of the pictures in a deck, the README’s image example passes an LLM client and a model name.

For newcomers and experts

If you are new. Markdown is plain text with light markers for headings, lists and tables. The README says mainstream LLMs natively “speak” Markdown and that its conventions are token-efficient. An Office file or a PDF is not plain text. MarkItDown reads it and writes out the text with its structure. Start with the command line, one file at a time, and read the result before you build on it.

For experts. convert() takes local files, remote URIs and byte streams, so the README tells you to use the narrowest call. That means convert_local() for local files, convert_response() after your own requests.get(), and convert_stream() for full control. Plugins register converters through the markitdown.plugin entry point and a register_converters() function. The OCR plugin registers its converters at priority -1.0, ahead of the built-in ones at 0.0.

Document Intelligence takes a model id, analysis add-ons and query fields. A model that returns structured fields puts them in YAML front matter. Content Understanding picks an analyzer for each file type, or uses the one you name with cu_analyzer_id. Its cu_file_types option limits which formats go to the cloud.

Good to know

The README’s table lists the built-in converters’ document conversion as offline and their cost as “Local compute only”. A remote URI or a YouTube URL is fetched over the network, and the README does not say whether audio transcription runs offline. The options below widen what it can reach.

• Your permissions: the README says MarkItDown performs I/O with the privileges of the current process, like open() or requests.get(). In an untrusted setting, sanitize the input. In a hosted or server-side app, restrict file paths, URI schemes and network destinations
• The MCP server: it has no authentication and runs as the user who starts it. Its tool can read any file that user can read, or fetch data from the network. It binds to localhost by default, and the README says not to bind it to other interfaces
• Cloud and LLM calls: Document Intelligence and Content Understanding are billable Azure calls that send your file to Azure. An LLM client sends images to the model you set. The OCR plugin sends each embedded image, plus each page of a scanned PDF rendered at 300 DPI as a full-page image
• Fit: the output is made for text analysis tools. The README says it may not be the best option for high-fidelity conversions that people will read
• Plugins: plugins are off by default. The MCP server’s Dockerfile sets MARKITDOWN_ENABLE_PLUGINS to True
• Versions: the README describes the main branch. On 3 November 2026 the MCP package’s PyPI page listed alpha versions only
• Usage data: the README says nothing about it, and the maker’s Dockerfiles set ORT_DISABLE_TELEMETRY=1
• Removal: the README gives no uninstall steps. Delete the virtual environment you made for it, or use pip’s own uninstall for each package
• License: MIT. The LICENSE file reads “Copyright (c) Microsoft Corporation.” Microsoft’s trademark terms apply to its names and logos