zcaceres/markdownify-mcp · 上手攻略

仓库：zcaceres/markdownify-mcp
链接：https://github.com/zcaceres/markdownify-mcp
分类：skill
作者：Tom
更新：2026-07-13

这是什么

Markdownify MCP Server 是一个基于 Model Context Protocol（MCP）的服务器，专门用于将各类文件和网页内容统一转换为 Markdown 格式。它本质上是给 AI 助手（尤其是 Claude Code 这类桌面 AI 编程工具）提供了一个文件内容提取的"桥梁"——让 AI 能直接读取 PDF、音频、表格、网页、YouTube 字幕等非文本内容，而无需自行处理复杂的解析逻辑。

核心依赖是 markitdown[all]（Python 包），该服务将其封装为 MCP 协议的工具接口，供所有兼容 MCP 的客户端（如 Claude App、Cursor 等）调用。

解决什么问题

在 AI 辅助编程场景中，AI 往往只能读取纯文本代码文件。当需要 AI 分析一份 PDF 文档、一段会议录音、一张截图的文字、或者一个 Excel 表格时，传统方案需要人工转换格式再粘贴。使用 Markdownify MCP 后，AI 可以在对话中直接调用工具，将任意支持的格式转为 Markdown 返回，全程无需人工介入。

典型痛点： - 需要 AI 总结一份 PDF 报告，但不知道如何把 PDF 内容给 AI - 有一张截图需要 AI 分析其中的文字，需要 OCR - 有一份 Excel 表格想让 AI 帮写分析逻辑 - 想让 AI 观看 YouTube 视频并总结内容

快速安装

前置要求

Bun（JavaScript 运行时，用于运行 MCP 服务器）
Python 3.x（用于 markitdown 依赖）

安装步骤

# 1. 克隆仓库
git clone https://github.com/zcaceres/markdownify-mcp.git
cd markdownify-mcp

# 2. 安装依赖（Bun 会自动创建 Python 虚拟环境 .venv 并安装 markitdown）
bun install

# 3. 构建 TypeScript
bun run build

# 4. 启动服务器
bun start

Docker 方式（适合生产环境）

docker build -t markdownify-mcp .
docker run --rm -i \
  -v "$HOME/Documents:/data:ro" \
  -e MD_ALLOWED_PATHS=/data \
  markdownify-mcp

⚠️ Docker 镜像默认只安装了 markitdown[pdf]，音频转录和图片 OCR 功能需要本地完整安装（bun install）才可用。

在桌面 App 中配置 MCP

以 Claude App 或其他 MCP 兼容客户端为例，在配置文件中添加：

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "/absolute/path/to/markdownify-mcp/dist/index.js"
      ]
    }
  }
}

核心用法

启动服务后，AI 客户端会自动发现以下 MCP 工具：

常用工具速览

工具名	功能
`pdf-to-markdown`	PDF 文件转 Markdown
`image-to-markdown`	图片 OCR，提取文字 + 元数据
`audio-to-markdown`	音频文件转录（Whisper 等）
`docx-to-markdown`	Word 文档转 Markdown
`xlsx-to-markdown`	Excel 表格转 Markdown 表格
`pptx-to-markdown`	PPT 幻灯片转 Markdown
`youtube-to-markdown`	YouTube 视频字幕提取
`webpage-to-markdown`	任意网页内容提取
`bing-search-to-markdown`	Bing 搜索结果整理
`get-markdown-file`	读取已有 Markdown 文件

实际使用示例（AI 对话中）

用户：帮我总结一下这份 PDF 报告的核心观点
AI： (调用 pdf-to-markdown 工具处理用户上传的 report.pdf)
   (返回 Markdown 格式内容)
   (AI 开始总结)

用户：提取这个网页的技术要点
AI： (调用 webpage-to-markdown 工具)
   (返回干净的文章文本)

环境变量配置

变量	默认值	用途
`MARKITDOWN_PATH`	`.venv/bin/markitdown`	markitdown 可执行文件路径
`REPOMIX_PATH`	`node_modules/.bin/repomix`	git-repo-to-markdown 工具路径
`MD_ALLOWED_PATHS`	无限制	允许读取的目录白名单（用 `:` 分隔）

# 限制只允许读取 /data 目录
MD_ALLOWED_PATHS=/data bun start

典型适用场景

AI 编程助手增强：在 Claude Code 中让 AI 直接分析项目中的 PDF 文档、设计稿截图、数据表格
音视频内容分析：提取 YouTube 视频字幕、会议录音转写，让 AI 做总结或问答
知识库构建：批量将 DOCX/PDF 资料转 Markdown，建立可搜索的知识库
自动化文档处理流水线：配合脚本定期抓取特定网页内容并转为 Markdown 存档

坑与注意

Bun 是必须的：项目基于 TypeScript/Bun 开发，不支持纯 Node.js 或 Deno
Python 虚拟环境由 preinstall 自动创建：无需手动 python -m venv，但如果 markitdown 安装失败，可能需要手动检查 .venv 状态
音频/图片功能需要 [all] 拓展：基础 pip install markitdown 只有 PDF 支持，完整功能需 pip install "markitdown[all]"
Docker 镜像功能不全：官方 Docker 镜像为节省体积默认只装 PDF 支持，要完整功能请用本地 Bun 安装
MD_ALLOWED_PATHS 是安全边界：生产环境务必设置，防止 AI 通过 MCP 工具读取敏感文件
文件路径在 Docker 中要注意：容器内路径和宿主机路径不同，要用容器内的挂载路径

与同类对比

工具	类型	特点
Markdownify MCP	MCP Server	多格式转 Markdown，AI 编程工具集成好
markitdown	Python CLI	直接命令行转换，无需 MCP
repomix	CLI	将整个代码仓库转为 Markdown，用于 AI 代码审查
MarkItDown（Microsoft）	CLI/Web	微软开源，支持更多 Office 格式

Markdownify MCP 的核心优势是 MCP 协议集成——它把 markitdown 的能力以 AI 友好的工具接口暴露出来，而非要求用户手动调用 CLI。对已经使用 Claude Code 等 MCP 客户端的用户，这是最低摩擦的方案。

一句话推荐结论

如果你在用 AI 编程助手并希望它能直接处理 PDF、截图、音频、表格等多模态文件，Markdownify MCP 是目前最省心的集成方案——装好、配置好，AI 就能"看到"这些内容了。