Workflows
MarkItDown
Microsoft’s Python tool for turning office documents into Markdown that a model or agent can read.
microsoft/markitdown is MIT licensed. It is a Python tool that converts common office files into Markdown. The point is to give a model or coding agent a text structure, not a binary file to guess at.
Use it when an agent needs to read a document you already have the right to process. Try it on a short file first, then wire it into a workflow. The converted text still belongs to the original work. Do not republish someone else’s document after conversion.
Mentioned by:
- @0x_rody mentioned this project on 14 November 2026 (26 likes and 0 reposts, captured 15 November 2026).
This page is a guide, not the original text.
What problem it solves
MarkItDown (repository microsoft/markitdown) is Microsoft’s Python utility for converting common office files into Markdown that a model or coding agent can read. It tries to keep structure such as headings, lists, tables, and links. Official docs also say the output is often readable, but the goal is still text analysis, not high-fidelity conversion for human layout work.
The repository also ships an official MCP package, markitdown-mcp. It exposes one tool, convert_to_markdown(uri), which accepts http:, https:, file:, or data: URIs. This page covers the CLI, the Python API, and that official MCP server.
Who it is for
It is for people who want an agent to read a PDF, Word, PowerPoint, Excel, or other file they already have the right to process. The project is MIT-licensed. It requires Python 3.10 through 3.14. Official docs recommend a virtual environment so dependencies do not clash.
The converted text is still subject to the original work’s copyright. Do not republish someone else’s document after conversion. Try a short file you are allowed to process before you wire it into a workflow.
How to install it
Checked on 15 November 2026 (Asia/Shanghai) against the repository README and the official MCP package README at packages/markitdown-mcp/README.md.
CLI and Python
The simplest install includes every optional extra:
python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[all]'If you only need some formats, install those extras instead, for example pip install 'markitdown[pdf, docx, pptx]'. Official optional extras include pptx, docx, xlsx, xls, pdf, and outlook, plus Azure Document Intelligence, Azure Content Understanding, audio transcription, and YouTube transcription.
CLI usage looks like this:
markitdown path-to-file.pdf -o document.mdYou can also pipe a file in with cat path-to-file.pdf | markitdown. In Python:
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.markdown)Plugins are off by default. Image captions, which official docs currently describe for pptx and image files, need you to supply llm_client and llm_model. Image captioning, speech transcription, and the two Azure cloud services all call hosted APIs. If you must stay local, install only the extras you intend to use.
MCP
pip install markitdown-mcp
markitdown-mcpSTDIO is the default. For Streamable HTTP and SSE, official docs use:
markitdown-mcp --http --host 127.0.0.1 --port 3001Official docs stress that this MCP package is for local use with trusted agents. HTTP and SSE bind to localhost by default. Do not bind the server to other interfaces unless you understand the security implications. The server has no authentication and runs with the privileges of the user who started it. convert_to_markdown can read any file or network resource that user can reach.
For Claude Desktop, official docs recommend the Docker image and give this config:
{
"mcpServers": {
"markitdown": {
"command": "docker",
"args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
}
}
}To convert local files, mount a directory into the container, typically at /workdir, as the MCP README shows. The root README does not give ready-made Cursor or Claude Code snippets. Other MCP clients that accept a standard stdio command can run markitdown-mcp, but this page does not invent client-specific config that official docs do not provide.
A worked example
The steps below are a check written for this page, not a canned official phrase. They were not run in this review, so the page does not invent the converted Markdown.
- Take a short PDF you have the right to process and place it in the current directory, for example
sample.pdf. - In the activated virtual environment, run:
markitdown sample.pdf -o sample.md- Open
sample.mdand check whether headings, lists, and tables survived, and whether sentences were split in odd places. Official docs say this is not a high-fidelity layout tool. Issue #2370 (still open on 15 November 2026) reports PDF paragraph breaks in the middle of sentences. - If you use the MCP server, send:
Convert file:///absolute/path/to/sample.pdf to Markdown with convert_to_markdown. Do not fetch any other URI.Compare the result with your CLI output instead of assuming they are identical.
Common pitfalls
- Installing the core package and then trying to convert PDF or Office files. Those formats need optional extras. If conversion fails, check whether you installed
markitdown[all]or the specific extras you actually use. - Passing untrusted input to
convert(). The official security section says MarkItDown performs I/O with the privileges of the current process, likeopen()orrequests.get(). If you only convert local files, call the narrowerconvert_local(). If you want to control downloads yourself, fetch first and then callconvert_response()orconvert_stream(). - Binding the MCP server to a non-local interface. The official MCP README repeats that the default bind is
localhostand that there is no authentication. Any process on the same machine can reach it. - Treating the Markdown as something you can publish at will. Conversion changes format, not rights. Do not send files that hold secrets or unpublished contracts into an untrusted environment.
FAQ
Do I have to install every optional extra?
No. markitdown[all] is the convenient option, but you can install only the extras you need, such as pdf and docx. Installing less also helps you avoid turning on features that call the network.
Do the MCP server and the CLI produce the same output?
The official MCP package calls the same MarkItDown library, through convert_to_markdown(uri). This page did not run the two entry points side by side, so it does not claim the output is identical. If they differ, compare the URI, plugin flags, and optional extras first.
Can it convert web pages or YouTube URLs?
The README lists HTML and YouTube URLs as supported sources. YouTube transcription is an optional extra and uses a hosted service. This page did not run those sources. For remote URIs, follow the official input-sanitizing guidance and do not point the agent at addresses you do not intend to fetch.
Does Claude Desktop require Docker?
The official MCP README recommends the Docker image for Claude Desktop and shows a claude_desktop_config.json example for that path. It does not present a local markitdown-mcp command as the recommended Claude Desktop config.
Can it replace a dedicated OCR or typesetting tool?
Official docs position it for LLMs and text-analysis pipelines, not high-fidelity reading for humans. For scans, complex tables, or structured field extraction, the README points to Azure Document Intelligence or Azure Content Understanding. Those are separate cloud services, with their own credentials and billing.
Sources and license
microsoft/markitdown and its MCP package are licensed under MIT. This page follows the root README and the markitdown-mcp README as of 15 November 2026, rewritten for CQBase — Context & Query Base. If the install commands, the Python range, or the MCP bind defaults change, follow those official pages.
In this category
- Workflows
Firecrawl
A web-crawling library for AI agents, licensed AGPL-3.0. The official MCP server is cataloged separately.
firecrawl - Workflows
Claude Code
Anthropic’s terminal coding agent: it reads the repo, edits files, and runs commands.
anthropics - Workflows
OpenAI Codex CLI
OpenAI’s lightweight terminal coding agent, Apache-2.0.
openai