markdownify-mcp · 协议与工具集成

把"乱七八糟的文件"变成 AI 友好的 Markdown：Markdownify MCP Server

一个让 AI 读懂一切的工具

想象一下：你手上有一堆 PDF 报告、Word 文档、图片截图、会议录音，还有一堆网页收藏夹——现在想让 Claude 或 Cursor 帮你处理它们。正常情况下，你得手动复制粘贴，或者用 Pandoc 命令行转来转去。

Markdownify MCP Server 就是来解决这个问题的：它是一个 MCP（Model Context Protocol）服务器，把各种格式的文件和网页内容，统一转换成干净的 Markdown 文本，让 AI 工具直接消化。

它支持的格式包括：

输入类型	工具名称	说明
PDF 文件	`pdf-to-markdown`	提取 PDF 文字内容
图片	`image-to-markdown`	含元数据和 OCR 描述
音频	`audio-to-markdown`	自动转录（Whisper）
DOCX	`docx-to-markdown`	Word 文档转换
XLSX	`xlsx-to-markdown`	Excel 表格转换
PPTX	`pptx-to-markdown`	PPT 幻灯片转换
YouTube	`youtube-to-markdown`	提取视频字幕
网页	`webpage-to-markdown`	通用网页抓取
Bing 搜索	`bing-search-to-markdown`	搜索结果转换

作者 zcaceres 的核心思路是：AI 工作流中的"数据孤岛"问题，归根结底是格式不统一。Markdownify 充当一个统一的"翻译层"，让任何文件都能被 AI 工具无差别地理解和处理。

技术架构：TypeScript + Python 双语言设计

项目采用 TypeScript（前端/胶水层）+ Python（底层转换引擎） 的混合架构：

TypeScript 部分：基于 @modelcontextprotocol/sdk 构建 MCP 服务器，定义了 10 个工具（tools），处理请求路由、参数校验、文件路径安全管控。
Python 部分：底层依赖 markitdown[all] 库（支持 PDF 解析、图像 OCR、音频转录等），通过 execFile 异步调用 Python 可执行文件。

核心文件结构：

src/
  server.ts      # MCP 服务器主入口，定义请求处理路由
  tools.ts       # 10 个工具的 schema 定义（基于 Zod）
  Markdownify.ts # 转换引擎，调度 markitdown CLI + HTTP 抓取
  utils.ts       # 路径安全校验（MD_ALLOWED_PATHS）、URL 验证

值得注意的是 路径安全机制（MD_ALLOWED_PATHS 环境变量）：服务器默认不对文件访问做限制，但通过设置该变量，可以限定工具只能读取指定目录下的文件，防止恶意路径穿越。这对于在生产环境中暴露 MCP 服务至关重要。

部署方式：Docker 是最省心的选择

项目提供了两种部署路径：

方式一：Docker 部署（推荐）

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

Dockerfile 采用多阶段构建（base → builder → runner），最终镜像基于 oven/bun:debian，包含 Python 3 和 markitdown，体积约 200MB。发布到 Docker Hub 的镜像为 mcp/server/markdownify，支持 Cosign 签名验证。

方式二：Bun 本地开发

bun install          # 自动触发 preinstall.js 创建 .venv
bun run build        # TypeScript 编译
bun start            # 启动服务

preinstall.js 会在 bun install 时自动创建 Python venv 并安装 markitdown[all]，体验相当顺滑。但要注意：音频转录和图片 OCR 功能需要 [all] 扩展，Docker slim 镜像默认不带。

应用场景与局限

适合的场景：

AI 助手（Claude Desktop、Cursor）作为知识库查询工具，直接读取本地 PDF/文档
研究人员将 YouTube 讲座转录为可搜索的 Markdown 笔记
自动化工作流：定期抓取网页内容并整理为 Markdown 存档

需要知道的局限：

SPA（单页应用）无法处理：代码中明确检测 isUnconvertedHtml，如果页面返回原始 HTML（通常是 JS 渲染的页面），会抛出错误并拒绝。这是 markitdown 的固有限制。
音频转录依赖 markitdown：若 markitdown 未安装 [all] 扩展，audio-to-markdown 会静默失败。
无 Web UI：纯 MCP 工具，不是 GUI 应用，需要搭配 Claude Desktop 或其他 MCP 客户端使用。
路径安全需要手动配置：默认不限制文件访问，生产环境务必配置 MD_ALLOWED_PATHS。

行业意义：MCP 生态的"瑞士军刀"

2024 年底 Anthropic 发布 MCP 协议后，围绕它的工具生态快速繁荣。Markdownify MCP Server 的出现代表了 MCP 工具的一种典型模式：协议适配层 + 专业后端。它不重复造轮子，而是将成熟的 Python 工具（markitdown、repomix）包装为 MCP 工具，充当 AI 与各种数据源之间的桥梁。

这种架构的好处是：Python 生态有大量成熟的内容解析库（PDF 解析、OCR、音频处理），TypeScript 侧只需处理 MCP 协议和请求路由，职责分离清晰。

截至目前，该项目在 GitHub 拥有 2,700+ stars，被收录至 Glama AI 的 MCP 服务器目录和 Docker Hub 官方 MCP 镜像库，表明其在 MCP 生态中已有一定的认可度。

把"乱七八糟的文件"变成 AI 友好的 Markdown：Markdownify MCP Server

一个让 AI 读懂一切的工具

它支持的格式包括：

输入类型	工具名称	说明
PDF 文件	`pdf-to-markdown`	提取 PDF 文字内容
图片	`image-to-markdown`	含元数据和 OCR 描述
音频	`audio-to-markdown`	自动转录（Whisper）
DOCX	`docx-to-markdown`	Word 文档转换
XLSX	`xlsx-to-markdown`	Excel 表格转换
PPTX	`pptx-to-markdown`	PPT 幻灯片转换
YouTube	`youtube-to-markdown`	提取视频字幕
网页	`webpage-to-markdown`	通用网页抓取
Bing 搜索	`bing-search-to-markdown`	搜索结果转换

技术架构：TypeScript + Python 双语言设计

项目采用 TypeScript（前端/胶水层）+ Python（底层转换引擎） 的混合架构：

TypeScript 部分：基于 @modelcontextprotocol/sdk 构建 MCP 服务器，定义了 10 个工具（tools），处理请求路由、参数校验、文件路径安全管控。
Python 部分：底层依赖 markitdown[all] 库（支持 PDF 解析、图像 OCR、音频转录等），通过 execFile 异步调用 Python 可执行文件。

核心文件结构：

src/
  server.ts      # MCP 服务器主入口，定义请求处理路由
  tools.ts       # 10 个工具的 schema 定义（基于 Zod）
  Markdownify.ts # 转换引擎，调度 markitdown CLI + HTTP 抓取
  utils.ts       # 路径安全校验（MD_ALLOWED_PATHS）、URL 验证

部署方式：Docker 是最省心的选择

项目提供了两种部署路径：

方式一：Docker 部署（推荐）

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

方式二：Bun 本地开发

bun install          # 自动触发 preinstall.js 创建 .venv
bun run build        # TypeScript 编译
bun start            # 启动服务

应用场景与局限

适合的场景：

AI 助手（Claude Desktop、Cursor）作为知识库查询工具，直接读取本地 PDF/文档
研究人员将 YouTube 讲座转录为可搜索的 Markdown 笔记
自动化工作流：定期抓取网页内容并整理为 Markdown 存档

需要知道的局限：

SPA（单页应用）无法处理：代码中明确检测 isUnconvertedHtml，如果页面返回原始 HTML（通常是 JS 渲染的页面），会抛出错误并拒绝。这是 markitdown 的固有限制。
音频转录依赖 markitdown：若 markitdown 未安装 [all] 扩展，audio-to-markdown 会静默失败。
无 Web UI：纯 MCP 工具，不是 GUI 应用，需要搭配 Claude Desktop 或其他 MCP 客户端使用。
路径安全需要手动配置：默认不限制文件访问，生产环境务必配置 MD_ALLOWED_PATHS。

行业意义：MCP 生态的"瑞士军刀"

这种架构的好处是：Python 生态有大量成熟的内容解析库（PDF 解析、OCR、音频处理），TypeScript 侧只需处理 MCP 协议和请求路由，职责分离清晰。

截至目前，该项目在 GitHub 拥有 2,700+ stars，被收录至 Glama AI 的 MCP 服务器目录和 Docker Hub 官方 MCP 镜像库，表明其在 MCP 生态中已有一定的认可度。