微软 MarkItDown：把 AI 看不懂的文件全翻译成 Markdown

背景

做 AI 应用开发的人都知道，喂数据是个技术活。AI 模型再强，如果你给它的文件格式它读不懂，一切都是白搭。PDF 里的文字、Word 文档里的表格、PPT 里的图片、邮件里的附件——这些东西在人类眼里一目了然，但丢给 AI 往往就变成了一堆乱码或者根本无法解析。

微软显然也看到了这个问题。2024 年 11 月，他们的 AutoGen 团队发布了一个 Python 工具叫 MarkItDown，目标很简单：把任何文件都转换成 AI 能读懂的 Markdown 格式。这个项目发布一年多，星标数从零涨到了 11.3 万，被 2600 多个项目依赖，说明这个需求确实是刚需。

这个视频来自"玉启智能"，是 Claude Code 生态解读系列的第三集。前两集分别讲了 superpowers（约束 AI 的行为）和 MCP servers（连接外部工具），这集讲的是数据问题——怎么把各种格式的文件喂给 AI。三集合在一起，构成了一个完整的 Claude Code 使用闭环。

MarkItDown 的核心定位说得很清楚：它不是为人看的，是为 AI 看的。 你不需要在乎转换出来的 Markdown 好不好看，只需要在乎 AI 能不能正确理解内容。

准备

环境要求

MarkItDown 基于 Python 开发，确保你的环境满足以下要求：

Python 3.9 或更高版本
pip 包管理工具
稳定的网络连接（用于下载依赖）

安装步骤只有两行命令，这就是视频里说的"两行命令就能用"：

bash

pip install markitdown

如果需要额外的格式支持，比如处理 PDF 中的图片 OCR，可以安装可选依赖：

bash

pip install markitdown[all]

支持的文件格式

MarkItDown 支持的格式相当全面，根据官方文档和社区测试，目前能处理的主要格式包括：

文档类：

PDF（支持扫描件 OCR）
Word 文档（.docx）
Excel 表格（.xlsx、.xls）
PowerPoint（.pptx）
HTML 网页
纯文本（.txt）

多媒体类：

图片（通过 OCR 提取文字）
音频文件（提取字幕/文字记录）
YouTube 视频（直接传入 URL 即可）

其他：

EPUB 电子书
CSV 数据文件
JSON / XML 结构化数据

需要注意的是，有些格式需要额外的依赖才能处理。比如 PDF OCR 功能需要安装相关的 OCR 引擎。安装 [all] 标签会把大部分常用依赖都装上。

安装 MCP Server 版本

MarkItDown 不仅是一个命令行工具，它还自带 MCP Server，可以直接集成到 Claude Code 等支持 MCP 协议的应用里。

安装 MCP Server 版本：

bash

pip install markitdown-mcp

或者通过 Smithery（一个 MCP 工具市场）一键安装：

bash

npx -y @smithery/cli install @KorigamiK/markitdown_mcp_server --client claude

MCP Server 版本提供了三个核心工具：

convert_file：转换单个文件
convert_directory：批量转换文件夹
list_supported_formats：查看支持的所有格式

步骤

一、命令行基础用法

MarkItDown 的命令行使用非常直观。最简单的用法：

bash

markitdown input.pdf -o output.md

这会把 input.pdf 转换成 output.md 文件。如果不指定输出文件名，它会直接打印到终端。

批量转换也很简单：

bash

markitdown ./documents/

这会处理 documents 文件夹下的所有支持的文件。

二、常用参数和选项

几个实用的命令行参数：

bash

# 指定输出文件
markitdown input.pdf -o output.md

# 处理整个文件夹
markitdown ./input_folder/ -o ./output_folder/

# 指定编码（处理中文文件时常用）
markitdown input.docx --encoding utf-8

# 保留图片到指定目录
markitdown input.pdf --images-dir ./images/

# 显示详细日志
markitdown input.pdf -v

三、MCP Server 集成用法

如果你用 Claude Code 或者其他支持 MCP 的工具，可以把 MarkItDown 配置成本地 MCP Server。

配置 Claude Desktop

打开 Claude Desktop 的配置文件（通常在 ~/Library/Application Support/Claude/claude_desktop_config.json），添加：

json

{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp",
      "args": []
    }
  }
}

在 Claude Code 中使用

配置完成后，就可以在对话中直接调用：

请用 MarkItDown 把这个 PDF 文件转换成 Markdown：/path/to/document.pdf

Claude Code 会调用 MCP 工具，把文件转换后直接读取内容，整个过程不需要你手动处理文件。

四、处理 YouTube 视频

MarkItDown 支持直接传入 YouTube 视频链接，自动提取字幕并转换成 Markdown：

bash

markitdown "https://www.youtube.com/watch?v=VIDEO_ID"

这个功能在处理教程视频、演讲、访谈时特别有用。你可以快速把视频内容转成文字稿，然后喂给 AI 分析或者总结。

五、Python API 用法

除了命令行，MarkItDown 也提供了 Python API，可以集成到你的代码里：

python

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

带可选依赖的用法（支持更多格式）：

python

from markitdown import MarkItDown

md = MarkItDown(enable_ocr=True, enable_table=True)
result = md.convert("scanned_document.pdf")
print(result.text_content)

六、RAG 工作流集成

MarkItDown 在 RAG（检索增强生成）场景中特别有用。一个典型的 RAG 流程：

读取原始文档（PDF、Word、PPT 等）
用 MarkItDown 转换成 Markdown
分割成合适的 chunks
存入向量数据库
检索时用相关 chunks 增强 AI 的回答

代码示例：

python

from markitdown import MarkItDown
from langchain.text_splitter import RecursiveCharacterTextSplitter

# 1. 转换文档
md = MarkItDown()
result = md.convert("technical_report.pdf")
markdown_content = result.text_content

# 2. 分割文本
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
chunks = splitter.split_text(markdown_content)

# 3. 存入向量数据库（后续步骤略）

七、与 LangChain 集成

如果你的项目使用 LangChain，可以通过 MCP Server 集成 MarkItDown：

python

from langchain.agents import initialize_agent
from langchain.tools import Tool

# 通过 MCP 调用 MarkItDown
file_uri = "file:///path/to/document.pdf"
messages = [
    ("user", f"Convert {file_uri} to markdown using MarkItDown MCP")
]

# Agent 会自动调用 MCP 工具完成转换

常见问题

Q1: 中文 PDF 转换出来乱码怎么办？

这是最常见的问题。解决方案：

确保安装了支持中文的依赖：

bash

pip install markitdown[all]

或者单独安装中文字体相关的 OCR 引擎
尝试用 --encoding utf-8 参数指定编码
如果是扫描件 PDF，确保 OCR 功能正常开启

Q2: PDF 里的表格转换效果不好？

MarkItDown 在持续优化表格提取功能。如果你发现表格转出来的格式混乱，可以：

等待版本更新（团队在持续改进）
考虑用专门的 PDF 表格提取工具做预处理
用 MarkItDown 转出后手动调整表格格式

Q3: YouTube 视频提取失败？

可能的原因：

视频没有字幕
网络问题无法访问 YouTube
视频被设为私有或地区限制

解决方法：确保网络畅通，或者手动下载字幕文件后再处理。

Q4: 支持的格式里没有我需要的？

MarkItDown 虽然支持 29+ 种格式，但不可能覆盖所有场景。如果遇到不支持的格式：

先转换成它支持的中间格式（比如把特殊格式转成 PDF）
或者用其他工具做格式转换，再用 MarkItDown 处理
可以在 GitHub 上提 Issue，团队会考虑添加支持

Q5: MCP Server 连接不上？

排查步骤：

确认已正确安装：pip list | grep markitdown
检查配置文件 JSON 格式是否正确
重启 Claude Desktop 应用
查看 Claude Desktop 日志排查具体错误

排错

问题一：安装失败

可能原因：

Python 版本过低
pip 版本过旧
缺少编译依赖（某些格式处理库需要编译）

解决方法：

升级 Python 到 3.9+
升级 pip：pip install --upgrade pip
安装编译依赖（Linux 上可能需要 build-essential、python3-dev 等）
使用虚拟环境避免依赖冲突

问题二：文件转换超时

可能原因：

文件体积太大
网络连接不稳定（处理远程文件时）
OCR 处理耗时较长

解决方法：

先把远程文件下载到本地再处理
拆分大文件为多个小文件
增加超时时间（某些 API 调用支持 timeout 参数）
关闭 OCR 功能以提升速度（不需要 OCR 时）

问题三：转换结果丢失格式

可能原因：

源文件格式复杂（多层嵌套结构）
对应的格式解析器不够完善
某些特性在 Markdown 中无法表达

解决方法：

检查是否有对应的插件可以安装
接受 Markdown 的表达限制，调整预期
对于复杂格式，考虑保留原始文件，仅用 MarkItDown 提取文字内容

问题四：MCP 工具调用报错

可能原因：

MCP Server 没有正确启动
配置文件路径错误
工具名称拼写错误

解决方法：

手动运行 markitdown-mcp 命令，检查是否能正常启动
核对配置文件中的路径是否正确
查看 Claude Code 的 MCP 日志获取详细错误信息
尝试重新安装 MCP Server 版本

结论

MarkItDown 解决了什么问题

一句话：它让 AI 能读懂世界上绝大多数的文件格式。

在此之前，如果你想把一份 PDF 报告喂给 AI 分析，通常需要自己写代码解析 PDF 结构、处理编码问题、提取文字和图片。这不仅门槛高，而且处理效果参差不齐。

MarkItDown 的价值在于：微软 AutoGen 团队帮你把这些脏活累活都做了，而且因为背靠微软的文档处理技术积累，效果通常比自己写的解析器要好。

适合的使用场景

RAG 知识库构建：把历史文档、报告、手册转成 Markdown 后存入向量库
AI 工作流自动化：让 AI Agent 能够读取各种格式的附件
数据迁移：把旧系统的文档批量转换成可编辑的 Markdown
视频内容提取：把教程视频的字幕转成文字稿
Claude Code 生态：配合 MCP 协议，实现"丢文件给 AI"的自然交互

和其他工具的对比

工具	优势	劣势
MarkItDown	微软背书、格式覆盖广、MCP 原生支持	某些复杂格式效果有限
MinerU	公式、表格提取强	配置复杂
Marker	注重排版还原	格式支持较少
Docling	结构化提取能力强	生态较新

没有绝对的最好，只有最适合你的场景。如果你在用 Claude Code 生态，MarkItDown 是最顺滑的选择。

三集闭环的意义

视频提到的三集系列其实揭示了一个趋势：AI 编程正在从"单点工具"走向"工具链协作"。

EP01 Superpowers：解决 AI 行为约束问题
EP02 MCP Servers：解决工具连接问题
EP03 MarkItDown：解决数据输入问题

这三者加在一起，才构成了一个完整的 AI 工作流：约束 AI 的行为 → 连接必要的工具 → 喂给它能看懂的数据。

来源

视频标题： 11.3 万星 markitdown: 微软把 AI 看不懂的文件全翻译了
频道： 玉启智能
链接： https://b23.tv/7Xne4P1
整理日期： 2026-05-10

微软 MarkItDown：把 AI 看不懂的文件全翻译成 Markdown ​

背景 ​

准备 ​

环境要求 ​

支持的文件格式 ​

安装 MCP Server 版本 ​

步骤 ​

一、命令行基础用法 ​

二、常用参数和选项 ​

三、MCP Server 集成用法 ​

配置 Claude Desktop ​

在 Claude Code 中使用 ​

四、处理 YouTube 视频 ​

五、Python API 用法 ​

六、RAG 工作流集成 ​

七、与 LangChain 集成 ​

常见问题 ​

Q1: 中文 PDF 转换出来乱码怎么办？ ​

Q2: PDF 里的表格转换效果不好？ ​

Q3: YouTube 视频提取失败？ ​

Q4: 支持的格式里没有我需要的？ ​

Q5: MCP Server 连接不上？ ​

排错 ​

问题一：安装失败 ​

问题二：文件转换超时 ​

问题三：转换结果丢失格式 ​

问题四：MCP 工具调用报错 ​

结论 ​

MarkItDown 解决了什么问题 ​

适合的使用场景 ​

和其他工具的对比 ​

三集闭环的意义 ​

相关资源 ​

标签 ​

来源 ​

微软 MarkItDown：把 AI 看不懂的文件全翻译成 Markdown

背景

准备

环境要求

支持的文件格式

安装 MCP Server 版本

步骤

一、命令行基础用法

二、常用参数和选项

三、MCP Server 集成用法

配置 Claude Desktop

在 Claude Code 中使用

四、处理 YouTube 视频

五、Python API 用法

六、RAG 工作流集成

七、与 LangChain 集成

常见问题

Q1: 中文 PDF 转换出来乱码怎么办？

Q2: PDF 里的表格转换效果不好？

Q3: YouTube 视频提取失败？

Q4: 支持的格式里没有我需要的？

Q5: MCP Server 连接不上？

排错

问题一：安装失败

问题二：文件转换超时

问题三：转换结果丢失格式

问题四：MCP 工具调用报错

结论

MarkItDown 解决了什么问题

适合的使用场景

和其他工具的对比

三集闭环的意义

相关资源

标签

来源