# MarkItDown

Canonical: https://cqbase.net/en/entry/markitdown
Chinese: https://cqbase.net/zh/entry/markitdown
English: https://cqbase.net/en/entry/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](https://x.com/0x_rody/status/2121328656094244982) mentioned this project on 14 November 2026 (26 likes and 0 reposts, captured 15 November 2026).

## 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](https://github.com/microsoft/markitdown) and the official MCP package README at [packages/markitdown-mcp/README.md](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/README.md).

**CLI and Python**

The simplest install includes every optional extra:

```bash
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:

```bash
markitdown path-to-file.pdf -o document.md
```

You can also pipe a file in with `cat path-to-file.pdf | markitdown`. In Python:

```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**

```bash
pip install markitdown-mcp
markitdown-mcp
```

STDIO is the default. For Streamable HTTP and SSE, official docs use:

```bash
markitdown-mcp --http --host 127.0.0.1 --port 3001
```

Official 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:

```json
{
  "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.

1. Take a short PDF you have the right to process and place it in the current directory, for example `sample.pdf`.
2. In the activated virtual environment, run:

```bash
markitdown sample.pdf -o sample.md
```

3. Open `sample.md` and 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](https://github.com/microsoft/markitdown/issues/2370) (still open on 15 November 2026) reports PDF paragraph breaks in the middle of sentences.
4. 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, like `open()` or `requests.get()`. If you only convert local files, call the narrower `convert_local()`. If you want to control downloads yourself, fetch first and then call `convert_response()` or `convert_stream()`.
- Binding the MCP server to a non-local interface. The official MCP README repeats that the default bind is `localhost` and 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](https://github.com/microsoft/markitdown) and its MCP package are licensed under MIT. This page follows the root README and the [markitdown-mcp README](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/README.md) 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.

## Catalog record

- Author: microsoft
- License: MIT
- Source: https://github.com/microsoft/markitdown
- Added: 2026-11-15
- GitHub stars: 195452 (captured 2026-11-15)

