万物皆可 Markdown！开源 MCP 服务器 Markdownify，10 种格式一键转换

一个 MCP 服务器，搞定 PDF、图片、音频、网页、Office 文档到 Markdown 的全部转换！

[1. 项目简介------它是什么？](#1. 项目简介——它是什么？)
[2. 它能做什么？------11 个工具全覆盖](#2. 它能做什么？——11 个工具全覆盖)
[3. 快速上手------3 步跑起来](#3. 快速上手——3 步跑起来)
[4. 核心原理------源码解析](#4. 核心原理——源码解析)
[5. Docker 部署与安全配置](#5. Docker 部署与安全配置)
[6. 适用场景与优缺点](#6. 适用场景与优缺点)
[7. 总结](#7. 总结)

1. 项目简介------它是什么？

Markdownify MCP 是一个基于 MCP（Model Context Protocol） 协议构建的开源服务器，核心使命非常简单：把几乎所有东西转成 Markdown。

想想你日常工作中遇到的这些场景：

📄 收到一份 PDF，想提取文本做笔记？ → 转 Markdown！
🖼️ 看到一张图，想得到描述和元数据？ → 转 Markdown！
🎵 录了一段音频，想要文字转录？ → 转 Markdown！
🌐 看到一个好网页，想保存内容？ → 转 Markdown！
📊 拿到 Excel 表格，想快速浏览？ → 转 Markdown！

这些需求，Markdownify 一个服务器全搞定 。它背后依托微软开源的 markitdown 工具作为转换引擎，再通过 MCP 协议让 AI 模型（比如 Claude、GPT）直接调用这些能力，实现「AI 读万物」的终极愿景。

🔗 项目地址：https://github.com/zcaceres/markdownify-mcp

📜 License：MIT

2. 它能做什么？------11 个工具全覆盖

Markdownify 提供了 11 个 MCP 工具，覆盖了你能想到的几乎所有常见格式：

工具名	输入类型	核心能力
`youtube-to-markdown`	YouTube URL	提取视频字幕/转录文本
`pdf-to-markdown`	PDF 文件路径	提取 PDF 全文为 Markdown
`bing-search-to-markdown`	Bing 搜索 URL	将搜索结果转为结构化 Markdown
`webpage-to-markdown`	网页 URL	爬取网页内容转为 Markdown
`image-to-markdown`	图片文件路径	提取图片描述 + 元数据
`audio-to-markdown`	音频文件路径	语音转文字（转录）
`docx-to-markdown`	DOCX 文件路径	Word 文档转 Markdown
`xlsx-to-markdown`	XLSX 文件路径	Excel 表格转 Markdown
`pptx-to-markdown`	PPTX 文件路径	PPT 演示文稿转 Markdown
`git-repo-to-markdown`	Git 仓库 URL	整个代码仓库打包成单份 Markdown
`get-markdown-file`	Markdown 文件路径	直接读取已有的 .md 文件

其中 git-repo-to-markdown 特别有意思------它底层用了 repomix 工具，能把一个完整 GitHub 仓库（文件树 + 源码）打包成一份 Markdown 文档，还能用 Tree-sitter 压缩把输出体积缩减约 70%！

3. 快速上手------3 步跑起来

Step 1：克隆项目 + 安装依赖

bash 复制代码

git clone https://github.com/zcaceres/markdownify-mcp.git
cd markdownify-mcp
bun install

⚠️ bun install 的 preinstall 步骤会自动创建 Python 虚拟环境 .venv 并安装 markitdown[all]（含 PDF、音频、OCR 等全部功能）。所以你不需要手动装 Python 依赖！

Step 2：构建项目

bash 复制代码

bun run build

Step 3：启动服务器

bash 复制代码

bun start

服务器就跑起来了！接下来把它接入你的 AI 桌面客户端。

接入桌面应用（如 Claude Desktop）

在你的 MCP 客户端配置中添加：

json 复制代码

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "/你的绝对路径/markdownify-mcp/dist/index.js"
      ]
    }
  }
}

保存后重启客户端，AI 就能直接调用以上 11 个工具了！

4. 核心原理------源码解析

Markdownify 的架构非常清晰，核心就三个模块：

🏗️ 架构概览

复制代码

MCP 客户端（Claude / 其他 AI）
         ↕ MCP 协议
    server.ts（路由层）
         ↕
    tools.ts（工具定义层）
         ↕
    Markdownify.ts（转换引擎层）
         ↕
    markitdown + repomix（底层工具）

🔧 server.ts ------ 请求路由

服务器注册了两个 MCP 请求处理器：

ListToolsRequestSchema：返回所有可用工具列表
CallToolRequestSchema：根据工具名分发调用

分发逻辑非常简洁，用 switch 语句按工具名路由：

typescript 复制代码

switch (name) {
  // URL 类工具（YouTube、Bing、网页）→ 传 url 参数
  case "youtube-to-markdown":
  case "bing-search-to-markdown":
  case "webpage-to-markdown":
    result = await Markdownify.toMarkdown({ url: validatedArgs.url });
    break;

  // 文件类工具（PDF、图片、音频、Office）→ 传 filePath 参数
  case "pdf-to-markdown":
  case "image-to-markdown":
  // ... ...
    result = await Markdownify.toMarkdown({ filePath: validatedArgs.filepath });
    break;

  // Git 仓库 → 调用专门的 fromRepo 方法
  case "git-repo-to-markdown":
    result = await Markdownify.fromRepo({
      repoUrl: validatedArgs.url,
      branch: validatedArgs.branch,
      compress: validatedArgs.compress,
    });
    break;
}

🔧 tools.ts ------ 工具定义

每个工具用 MCP SDK 的 ToolSchema 定义，包含：

name：工具名（如 pdf-to-markdown）
description：功能描述
inputSchema：输入参数（filepath 或 url）
annotations：标注 readOnlyHint: true（只读工具，不修改文件）

设计上遵循 只读原则------所有工具都是读取内容并转换输出，不会修改原始文件。

🔧 转换引擎

底层转换实际由两个工具完成：

markitdown（微软开源）：处理 PDF、图片、音频、Office 文档等本地文件转换
repomix：处理 Git 仓库打包为 Markdown（支持 Tree-sitter 压缩）

5. Docker 部署与安全配置

Docker 一键部署

bash 复制代码

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 功能需要 [all] extras，需本地安装才能使用完整功能。

安全配置------`MD_ALLOWED_PATHS`

这个服务器提供了路径安全机制，防止 AI 模型随意读取系统文件：

环境变量	默认值	作用
`MD_ALLOWED_PATHS`	未设置（不限制）	限制文件类工具只能读取指定目录（POSIX 用 `:` 分隔，Windows 用 `;`）
`MARKITDOWN_PATH`	项目内 `.venv/bin/markitdown`	markitdown 可执行文件路径
`REPOMIX_PATH`	项目内 `node_modules/.bin/repomix`	repomix 可执行文件路径

示例：只允许读取 /data/in 和 /data/out：

bash 复制代码

MD_ALLOWED_PATHS=/data/in:/data/out bun start

6. 适用场景与优缺点

✅ 适合谁用？

场景	说明
AI 应用开发者	给 AI 加上「读懂万物」的能力
知识管理爱好者	把各种格式内容统一为 Markdown 入库
自动化工作流	批量转换文档、提取信息
代码分析	`git-repo-to-markdown` 把整个仓库喂给 AI 分析

⚖️ 优缺点对比

优点	缺点
🟢 格式覆盖广（10 种文件 + 网页）	🔴 音频转录依赖 markitdown `[all]` extras，Docker 精简版不支持
🟢 MCP 协议标准，任何兼容客户端都能用	🔴 依赖 Python + Bun 双运行时，安装稍复杂
🟢 只读设计，安全可靠	🔴 转换质量依赖 markitdown 底层，复杂 PDF 可能丢失排版
🟢 支持 Docker 部署 + 路径安全机制	🔴 Bing 搜索仅支持 Bing，不支持 Google
🟢 Git 仓库转 Markdown 支持 Tree-sitter 压缩	🔴 项目相对年轻（v1.1.0），文档和生态还在成长

7. 总结

Markdownify MCP 用一个清晰优雅的设计，解决了 AI 与人类沟通的格式鸿沟问题------PDF、Word、Excel、PPT、图片、音频、网页、甚至整个代码仓库，统统变成 Markdown，让 AI 模型可以直接「阅读」。

它基于 MCP 协议，意味着任何兼容的 AI 客户端都能无缝接入；底层依托微软 markitdown 和 repomix 两个成熟工具，转换能力扎实。加上 Docker 部署和路径安全机制，生产环境也能放心用。

如果你正在构建 AI 应用，或者想让你的 AI 助手「读懂」更多东西，Markdownify MCP 是目前最全面的格式转换 MCP 服务器之一。

推荐指数：⭐⭐⭐⭐ (4/5)

格式覆盖全面、架构清晰、协议标准，但双运行时依赖和部分功能的精简镜像限制是小小遗憾。

原文链接 ：https://github.com/zcaceres/markdownify-mcp

License：MIT

标签：#GitHub #开源项目 #Markdownify #MCP #Markdown #AI工具 #格式转换

分类：原创文章

万物皆可 Markdown！开源 MCP 服务器 Markdownify，10 种格式一键转换