MarkItDown 是由微软开源的一款轻量级 Python 实用工具，专为将各种文件格式转换为结构化的 Markdown 而设计。在大型语言模型（LLM）时代，Markdown 因其接近纯文本的特性及极少的标记语法，成为了 LLM 最理想的输入格式之一，而 MarkItDown 则是打通非结构化文档与 LLM 之间的重要桥梁。

一、 MarkItDown 介绍

1.1 核心定位与原理

MarkItDown 的核心功能是将多种文件格式转换为 Markdown，同时注重保留文档中重要的结构和内容（如标题、列表、表格、链接等）。虽然其输出对人类阅读友好，但其主要服务对象是文本分析工具和 LLM，方便后续的索引、检索与分析。

从技术原理上看，MarkItDown 本质上是一个智能的“包装器”，它根据文件的扩展名自动选择并调用底层转换工具（例如：使用 mammoth 处理 DOCX，markdownify 处理 HTML，pandas 处理 Excel，pdfminer 提取 PDF 文本等），从而实现一站式转换。

1.2 支持的文件格式

MarkItDown 支持极为广泛的文件格式，涵盖了日常办公与多媒体处理的方方面面：

办公文档：PDF (.pdf)、Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx / .xls)、Outlook 邮件等。

多媒体文件：图像（支持 EXIF 元数据提取和 OCR 识别）、音频（支持 EXIF 元数据和语音转录）。

网页与数据：HTML（特化处理维基百科等）、CSV、JSON、XML。

其他格式：ZIP 压缩包（可迭代处理内部文件）、EPub 电子书、YouTube 链接（获取视频字幕转录）。

1.3 扩展能力与生态

除了基础转换，MarkItDown 还具备强大的扩展能力：

AI 智能增强：支持集成 OpenAI 等大型语言模型，通过多模态能力（如 GPT-4o）自动生成图像描述或优化文档结构。

Azure 文档智能：可接入 Azure Document Intelligence 服务，以获得更高质量的文档解析能力。

插件系统：支持第三方插件扩展，例如 markitdown-ocr 插件可以利用 LLM Vision 从嵌入式图像中提取文本，而无需额外的 ML 库。

MCP 协议支持：最新版本提供了 MCP（模型上下文协议）服务器，支持与 Claude Desktop、Cherry Studio 等 AI 应用深度集成。

二、 安装指南

2.1 环境准备

MarkItDown 需要 Python 3.10 或更高版本。为避免依赖冲突，强烈建议在虚拟环境中进行安装。

2.2 基础与全量安装

使用 pip 可以快速安装。如果希望一次性安装所有格式支持的依赖，可以使用 [all] 选项：

windows环境：

pip install markitdown[all]

如果只需要基础功能，可以省略选项：

pip install markitdown

2.3 按需安装（可选依赖项）

为了精细化控制环境，你可以只安装特定文件格式所需的依赖项，例如：

pip install markitdown[pdf, docx, pptx]

目前可用的可选依赖组包括：[pptx]、[docx]、[xlsx]、[xls]、[pdf]、[outlook]、[az-doc-intel]、[audio-transcription]、[youtube-transcription] 等。

2.4 MCP 服务器安装

若需与支持 MCP 的客户端集成，需单独安装：

pip install markitdown-mcp

三、 使用文档

3.1 命令行工具 (CLI)

CLI 适合快速转换和脚本集成，安装后即可在终端使用。

转换并输出到标准输出：

markitdown path-to-file.pdf

保存到指定文件（使用重定向或 -o 参数）：

markitdown path-to-file.pdf > output.mdmarkitdown path-to-file.pdf -o output.md

使用管道传输内容

cat path-to-file.pdf | markitdown

启用插件：默认插件是禁用的，可通过参数开启：

markitdown --use-plugins path-to-file.pdfmarkitdown --list-plugins #列出已安装插件

3.2 Python API

from markitdown import MarkItDownmd = MarkItDown(enable_plugins=False) 设置为 True 以启用插件result = md.convert("test.xlsx")print(result.text_content)

import iofrom markitdown import MarkItDownmd_converter = MarkItDown()with open('example.pdf', 'rb') as file:    markdown_output = md_converter.convert_stream(file)print(markdown_output)

from markitdown import MarkItDownfrom openai import OpenAIclient = OpenAI() 请确保已配置 OPENAI_API_KEY 环境变量md = MarkItDown(llm_client=client, llm_model="gpt-4o")result = md.convert("example.jpg")print(result.text_content)

3.4 MCP 服务器部署

针对集成了模型上下文协议（MCP）的 AI 客户端（如 Cherry Studio），可通过以下方式启动服务：

STDIO 模式（默认）

{  "servers": {    "markitdown": {      "command": "C:/Users/donghengxing/AppData/Roaming/Python/Python313/Scripts/markitdown-mcp.exe",      "args": [],      "transport": "stdio"    }  }}

SSE 模式：

markitdown-mcp --sse --host 127.0.0.1 --port 3001

配置客户端时，填入上述命令或可执行文件路径即可启用。

4、参考