MarkItDown-MCP二开:AI助手驱动的各类文件转Markdown

基于 [microsoft/markitdown](https://github.com/microsoft/markitdown) 的中文增强版，核心改进：**AI 助手驱动的 OCR 方案**，无需配置外部 LLM，通过 MCP 协议与 AI 助手（QoderWork / CodeBuddy / Qoder）深度协作，利用助手自身的视觉能力完成图片识别和文档分析。

项目背景

MarkItDown 是一个轻量级 Python 工具，用于将各类文件转换为 Markdown，主要服务于 LLM 和文本分析场景。它在保留文档结构（标题、列表、表格、链接等）的同时，输出对 AI 友好的 Markdown 文本。

支持的格式

类别	格式
文档	PDF、Word (.docx)、PowerPoint (.pptx)、EPUB
表格	Excel (.xlsx/.xls)、CSV、JSON、XML
图片	PNG、JPG、BMP、WebP 等（EXIF 元数据 + OCR）
音频	WAV、MP3（EXIF 元数据 + 语音转写）
网页	HTML、YouTube、Wikipedia、RSS
其他	ZIP（递归处理）、Outlook 邮件、Jupyter Notebook

原始设计的一个核心依赖是：当文档中包含图片时，需要配置外部 LLM（如 OpenAI GPT-4o）来进行图片内容识别和 OCR。这带来了额外的 API 成本、网络延迟和配置复杂度。

为什么需要改造

在实际使用中，我发现一个明显的冗余：当用户通过 AI 助手（如 QoderWork、CodeBuddy、Qoder）使用 markitdown 时，AI 助手本身就具备视觉能力。用户已经在和助手对话，却还要单独配置一个外部 LLM 来识别图片——这就像你面前坐着一位翻译，却还要打电话找另一位翻译。而且如果我买了AI助手的套餐订阅，我为什么还要再买一个套餐配给markitdown?

这引发了一个核心问题：能否让 AI 助手直接"看"文档中的图片，用自己的视觉能力完成识别，从而消除对外部 LLM 的依赖？

改造目标

零外部 LLM 依赖：图片识别完全由 AI 助手自身的视觉能力完成
保持兼容性：不改变 markitdown 的公共 API，新功能作为可选参数
MCP 协议集成：通过标准 MCP 协议暴露工具，AI 助手即插即用
数据高效：大文件（图片）走磁盘文件传输，不通过 MCP JSON 传递大量数据

核心特性：AI 助手驱动模式

传统方案需要单独配置 OpenAI 等外部 LLM 来驱动 OCR 和图片描述。本项目的 extract_only 模式彻底消除了这一依赖：

工作原理：

Phase 1 — 提取：MCP Server 的 analyze_document 工具将文档转换为文本骨架（Markdown），同时将嵌入的图片提取到磁盘临时目录，返回 JSON 格式的图片清单（路径、尺寸、位置）
Phase 2 — 识别：AI 助手通过 Read 工具直接读取磁盘上的图片文件，利用自身的视觉能力进行 OCR / 图表描述 / 内容分析
合并输出：助手将识别结果替换回文本骨架中的图片占位符，生成完整的 Markdown 文档

安装

环境要求

Python 3.10+（推荐 3.12/3.13）
建议使用虚拟环境

从源码安装（开发模式）

BASH

git clone https://github.com/mambo-wang/markitdown-mcp.git
cd markitdown-mcp

# 安装核心库
pip install -e packages/markitdown

# 安装 MCP Server
pip install -e packages/markitdown-mcp

使用方法

MCP Server 配置

MCP Server 提供三个工具：

工具	说明
`convert_to_markdown(uri)`	将 URI 资源转换为 Markdown（原有工具）
`analyze_document(path)`	提取文本骨架 + 图片清单（新增，用于 AI 助手协作）
`ocr_image(path, prompt)`	对单张图片进行视觉分析并返回描述文本（新增）

在 QoderWork 的 Connectors 设置中，添加自定义 MCP Server，粘贴以下配置：

JSON

{
  "mcpServers": {
    "markitdown": {
      "command": "C:\\Program Files\\Python313\\python.exe",
      "args": ["-m", "markitdown_mcp"]
    }
  }
}

将 `command` 路径替换为你的 Python 解释器路径。

AI 助手 Skill

项目提供 markitdown-convert Skill，为 AI 助手（QoderWork / CodeBuddy / Qoder）提供标准化的文档转 Markdown 工作流，涵盖格式分流、图片过滤、OCR 提取、结果组装等完整步骤。

安装 Skill

将 skills/markitdown-convert 目录拷贝到你项目的 skill 目录下：

BASH

# CodeBuddy
cp -r skills/markitdown-convert .codebuddy/skills/

安装后，当你对 AI 助手说"把这个文件转成 markdown"时，助手会自动匹配该 Skill 并按标准流程执行。

版本信息

组件	版本
markitdown	0.1.6
markitdown-mcp	0.0.1a5
MCP SDK	>=1.8.0（已验证 1.28.0）
MCP 协议	2025-11-25

实际使用案例

文字提取--提取文档中图片中的文字

喂给AI--Markdown是AI最熟悉的格式，转完之后丢给AI，它理解得特别准

知识库文档预处理--入库前的文档预处理

下面以qoderwork-cn+免费赠送的qwen3.7max结合本项目提供的skill和mcp看一下转换效果:

1 扫描版PDF转换

转换前：

转换后（markdown格式）：

2 有插图的PPT转换

转换前：

转换后（markdown预览）:

致谢

本项目基于 Microsoft 的 markitdown 进行增强开发。感谢 AutoGen Team 的原始工作。

代码地址:

https://github.com/mambo-wang/markitdown-mcp