markitdown-docs

name	markitdown-docs
description	Use when a task explicitly involves Microsoft MarkItDown/markitdown-mcp, or deciding whether to use MarkItDown to convert documents or URIs into Markdown for ingestion. Covers MarkItDown-specific extras, MCP behavior, plugins/OCR/Azure options, security boundaries, and format limitations; avoid for high-fidelity Office/PDF editing.

MarkItDown Docs

Core Use

Use MarkItDown as a document ingestion layer: convert supported source material to Markdown, inspect/search the Markdown, then summarize or extract from that output. Do not treat it as a high-fidelity Office/PDF editor.

What MarkItDown Adds

• Preserves useful document structure as Markdown: headings, lists, tables, links, and text content where converters support them.
• Supports PDF, DOCX, PPTX, XLSX/XLS, Outlook .msg, HTML, CSV, JSON, XML, EPUB, ZIP, images, audio, YouTube transcript URLs, and more.
• Provides CLI, Python API, plugin support, cloud-enhanced Azure paths, and an official MCP server.
• markitdown-mcp exposes one tool: convert_to_markdown(uri), accepting http:, https:, file:, and data: URIs.
• data: URIs can inline sensitive base64 content; avoid logging or pasting complete data URIs unless necessary.

Path Selection

• Simple local conversion: use CLI or Python MarkItDown().convert(...).
• Agent tool use: use markitdown-mcp; prefer STDIO for sensitive files. Localhost HTTP/SSE is convenient, not private isolation.
• Sensitive local-only work: prefer narrower APIs such as convert_local() or convert_stream() instead of broad convert().
• Caller-controlled network access: fetch the URL yourself with explicit restrictions, then use convert_response().
• Complex scanned PDFs, forms, invoices, receipts, or structured field extraction: consider Azure Content Understanding or Document Intelligence only when the user has approved that cloud service.
• Need workbook editing/calculation, formula/macro preservation, pivots, charts, or hidden-sheet fidelity: do not use MarkItDown as the main tool.
• Need Word/PPT round-trip layout editing: do not use MarkItDown as the main tool.

Install Profiles

Use targeted extras instead of [all] when possible:

python -m pip install "markitdown[pdf,docx,pptx,xlsx,outlook]"
python -m pip install "markitdown[xls]"
python -m pip install markitdown-mcp

Official extras to remember:

• [pptx], [docx], [xlsx], [xls], [pdf], [outlook]
• [audio-transcription], [youtube-transcription]
• [az-doc-intel], [az-content-understanding]
• [all] for broad support when dependency footprint is acceptable

MarkItDown-Specific Operations

• CLI conversion: markitdown input.ext -o output.md
• Plugin discovery: markitdown --list-plugins
• One-off plugin use: markitdown --use-plugins input.ext -o output.md
• Document Intelligence: markitdown input.pdf -o output.md -d -e "<endpoint>"
• Content Understanding: markitdown input.pdf --use-cu --cu-endpoint "<endpoint>" -o output.md
• MCP STDIO server: markitdown-mcp
• MCP local HTTP/SSE: markitdown-mcp --http --host 127.0.0.1 --port 3001
• MCP plugin enablement: set MARKITDOWN_ENABLE_PLUGINS=true; do not use CLI --use-plugins with MCP.

For Dockerized MCP, mount only the directory needed by the task, then pass file:///workdir/... URIs.

Optional Capabilities

• Plugins are disabled by default; enable only for a specific need.
• markitdown-ocr adds OCR for embedded images in PDF/DOCX/PPTX/XLSX using the same LLM-vision client pattern as image descriptions; without an LLM client, OCR is skipped.
• OCR through markitdown-ocr and LLM image descriptions send image content to the configured vision/LLM client unless that client is an approved local model.
• Azure Document Intelligence provides cloud layout extraction for documents.
• Azure Content Understanding provides cloud multimodal extraction, YAML front matter for structured fields, custom analyzers, audio/video analyzers, and stronger handling for complex/scanned documents.

Safety Boundaries

• MarkItDown performs I/O with the current process privileges. Validate untrusted paths, URI schemes, and network destinations.
• Do not send company documents, email attachments, images, audio, or extracted text to cloud/third-party services unless explicitly approved for that material.
• markitdown-mcp has no built-in authentication. Even localhost HTTP/SSE can be reached by same-machine users/processes and can read files/network data accessible to its process; use STDIO or a container/VM sandbox for sensitive material.
• Do not bind markitdown-mcp to non-localhost interfaces unless the user understands the exposure.
• Avoid broad recursive conversion over home directories, cloud-sync folders, mailbox exports, shared drives, or unknown ZIP files.

Format Limits To Remember

• Excel: Markdown tables/content only. Verify row counts and key totals; formulas, macros, charts, pivots, hidden sheets, comments, and styling are not reliable.
• PDF: text PDFs are usually fine; tables, columns, forms, footnotes, and scans require spot checks or OCR/layout tools.
• DOCX/PPTX: useful for text extraction; not a round-trip layout representation.
• Outlook .msg: saved-message extraction only; live mailbox operations need Outlook/Microsoft Graph tooling.
• Images/audio: quality depends on installed extras and approved OCR/vision/transcription services.
• Video: no built-in local converter; use Azure Content Understanding only when approved.
• ZIP and remote URLs: treat as untrusted input unless explicitly scoped.

Validation Habit

After conversion, check that output is non-empty and inspect relevant sections before answering. For high-stakes values, compare against the source or switch to a format-specific tool (openpyxl, Excel MCP, pdfplumber, PyMuPDF, OCR, DOCX/PPTX libraries, Microsoft Graph).