MarkItDown全面指南：微软开源文件转Markdown工具 ​

MarkItDown 是微软开源的轻量级 Python 工具，将各种文件格式转换为结构化的 Markdown。在 LLM 时代，Markdown 成为 LLM 最理想的输入格式之一，而 MarkItDown 是打通非结构化文档与 LLM 之间的重要桥梁。

一、核心定位与原理 ​

核心功能：将多种文件格式转换为 Markdown，保留文档重要结构（标题、列表、表格、链接等）。

主要服务对象：文本分析工具和 LLM，方便后续索引、检索与分析。

技术原理：根据文件扩展名自动选择并调用底层转换工具：

二、支持的文件格式 ​

三、扩展能力 ​

四、安装指南 ​

环境准备 ​

需要 Python 3.10 或更高版本，建议在虚拟环境中安装。

基础安装 ​

# 全量安装（所有格式支持）
pip install markitdown[all]

# 基础安装
pip install markitdown

按需安装 ​

pip install markitdown[pdf, docx, pptx]

可选依赖组：[pptx]、[docx]、[xlsx]、[xls]、[pdf]、[outlook]、[az-doc-intel]、[audio-transcription]、[youtube-transcription]

MCP服务器安装 ​

pip install markitdown-mcp

五、使用方法 ​

CLI命令行 ​

# 转换并输出到标准输出
markitdown path-to-file.pdf

# 保存到指定文件
markitdown path-to-file.pdf > output.md
markitdown path-to-file.pdf -o output.md

# 使用管道传输
cat path-to-file.pdf | markitdown

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

Python API ​

基础文件转换：

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)

文件流转换：

import io
from markitdown import MarkItDown

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

结合LLM进行图像智能描述：

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()  # 需配置 OPENAI_API_KEY
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

MCP服务器部署 ​

STDIO模式（默认）：

{
  "servers": {
    "markitdown": {
      "command": "markitdown-mcp.exe",
      "args": [],
      "transport": "stdio"
    }
  }
}

SSE模式：

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

总结 ​

开源地址：github.com/microsoft/markitdown

关键词：MarkItDown, 微软开源, 文件转Markdown, LLM工具, MCP服务器