MarkItDown — Convert Any Document to Markdown

What it is

MarkItDown is an open-source Python tool by Microsoft that converts a wide range of file formats into clean Markdown text. Supported inputs include Word documents, PowerPoint presentations, Excel spreadsheets, PDFs, images (with OCR), audio files (with transcription), and HTML pages. The tool also ships as an MCP server, making it directly usable by AI assistants like Claude Code.

The primary audience is developers building LLM pipelines who need to ingest structured documents without losing formatting context. Instead of writing format-specific parsers, you feed any file to MarkItDown and get consistent Markdown output.

How it saves time or tokens

Raw document formats like .docx or .pptx contain XML markup, styling metadata, and binary blobs that waste tokens when passed to an LLM. MarkItDown strips all non-content data and outputs compact Markdown, keeping headings, lists, tables, and emphasis intact. The token estimate for this workflow is 979 tokens, a fraction of what raw document XML would consume. The MCP server mode eliminates the need for manual conversion steps entirely.

How to use

1. Install the package:

pip install 'markitdown[all]'

1. Convert a file from the command line:

markitdown path/to/file.pptx > output.md
markitdown https://example.com/document.pdf > output.md

1. Use the Python API for programmatic conversion:

from markitdown import MarkItDown
md = MarkItDown()
result = md.convert('report.docx')
print(result.text_content)

Example

Using MarkItDown as an MCP server for Claude Code:

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp"
    }
  }
}

Once configured, Claude Code can call MarkItDown to convert documents inline during a conversation, extracting text from uploaded files without manual preprocessing.

Related on TokRepo

• AI Tools for Documents — more tools for document processing and conversion in AI workflows
• MCP Integrations — browse MCP servers that extend AI assistant capabilities

Common pitfalls

• Image-heavy PDFs require OCR dependencies (Tesseract); install them separately or use pip install 'markitdown[all]' to include all optional features
• Audio transcription depends on external speech-to-text APIs; configure API keys before attempting audio conversion
• Complex table layouts in Excel with merged cells may not convert perfectly; verify output for critical data extraction tasks