markdownify-mcp：用 MCP 协议把 PDF、网页、音视频统一转成 Markdown
模型上下文协议服务器，用于将几乎所有内容转换为 Markdown。
秒懂
- 它是什么？
- markdownify-mcp 是一个 TypeScript 写的 MCP 服务器，把 PDF、图片、音频、Office 文档和网页内容统一转成 Markdown。它依赖 markitdown 和 repomix 两个外部工具，部署方式灵活，但功能完整性受安装选项影响。
- 适合谁用？
- markdownify-mcp 适合已经使用 MCP 客户端（如桌面应用或 Docker 部署）且需要把多格式内容统一转为 Markdown 的工程师。它不适合对音频转写和图片 OCR 有硬性要求却只打算用 Docker 镜像的用户，因为官方镜像只装 markitdown[pdf]，这两个工具会直接失败。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 2 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是 MCP 生态里的格式孤岛问题
MCP 服务器让 AI 助手能调用外部工具，但每个工具只擅长一种输入。PDF 要一个解析器，音频要一个转写服务，网页又要另一个抓取器。markdownify-mcp 把这些都收拢到 Markdown 这一种输出格式里。它面向的是已经在用 MCP 协议的人，比如桌面应用或自定义 agent，而不是想单独转换某个文件的普通用户。README 明确列出了十种工具，从 pdf-to-markdown 到 get-markdown-file，覆盖文件、网页和检索三类操作。这个设计思路是：与其让模型处理多种原始格式，不如先统一成 Markdown，再让模型消费。
转换核心是 markitdown，MCP 层只是包装
仓库结构显示，服务器本身用 TypeScript 写，但真正的转换逻辑不在 TypeScript 里。安装时 preinstall 脚本会创建 Python 虚拟环境 .venv 并安装 markitdown[all]。启动后，pdf-to-markdown、image-to-markdown 这些工具会调用 .venv 里的 markitdown 可执行文件。这是一个明显的分层：MCP 负责协议交互和路径校验，markitdown 负责格式解析。另一个工具 git-repo-to-markdown 则依赖 repomix，它位于 node_modules/.bin/repomix。也就是说，这个项目是 glue code，不是算法实现。这带来一个后果：markitdown 的任何版本更新或行为变化，都会直接影响这里的输出质量，而项目本身无法控制。
安装和配置：bun 是前提，路径变量决定行为
README 给出的启动步骤很直接：克隆仓库，运行 bun install，然后 bun run build，最后 bun start。bun install 会触发 preinstall，自动创建 .venv 并安装 markitdown[all]。如果你不想用项目自带的虚拟环境，可以设置 MARKITDOWN_PATH 指向系统级安装，比如 pipx install "markitdown[pdf]" 后的可执行文件。REPOMIX_PATH 同理，默认指向项目内的 node_modules/.bin/repomix。桌面应用集成时，需要在 mcpServers 配置里指定 dist/index.js 的绝对路径。环境变量里最值得注意的是 MD_ALLOWED_PATHS，它用路径分隔符（POSIX 是冒号，Windows 是分号）列出允许读取的目录，一旦设置，所有文件输入工具都会拒绝目录外的路径。MD_SHARE_DIR 是它的旧别名，仍然生效。
Docker 部署有一个隐藏的功能缺口
Docker 用法看起来简单：构建镜像，挂载目录，设置 MD_ALLOWED_PATHS。但 README 明确警告，官方 Docker 镜像只安装 markitdown[pdf]，audio-to-markdown 和 image-to-markdown 依赖 [all] extras，在精简镜像里会失败。这意味着如果你用 Docker 部署，却期待音频转写和图片 OCR 能工作，就会踩坑。这不是文档没写，而是容易被忽略。本地用 bun install 才有完整功能。这个限制直接影响部署选型：需要完整功能，就得放弃 Docker 镜像的便利，自己管理本地环境。
路径限制是个安全特性，也是个使用约束
MD_ALLOWED_PATHS 的设计很直白：不设置就无限制，设置了就严格校验。对 MCP 服务器来说，这很重要，因为 AI 模型可能被提示词注入诱导去读任意文件。限制读取目录能降低风险。但这也意味着，如果你不设置，任何能调用这个服务器的客户端都能读取服务器进程能访问的所有文件。Docker 的示例里，挂载 $HOME/Documents 到 /data 并设置 MD_ALLOWED_PATHS=/data，这样工具只能访问容器内的 /data 路径。注意 README 强调，工具参数要传容器路径，不是宿主机路径，比如 /data/foo.pdf 而不是 /Users/you/Documents/foo.pdf。这是个容易出错的地方，尤其是习惯本地路径的用户。
与直接调用 markitdown 相比，它多了协议层，少了灵活性
如果你只是想转换文件，直接安装 markitdown 然后跑命令行可能更简单。markdownify-mcp 的价值在于它把转换能力暴露成 MCP 工具，让 AI 客户端能动态调用。但代价是增加了一层间接：你需要维护 MCP 服务器进程，处理环境变量，还要理解 markitdown 的依赖。另一个替代方案是使用其他 MCP 服务器，比如专门处理 PDF 的服务器或专门的网页抓取服务器，但它们通常只覆盖单一格式。markdownify-mcp 的优势是覆盖面广，缺点则是每个工具都依赖外部可执行文件，一旦某个依赖缺失或版本不匹配，对应的工具就会静默失败或报错。
维护成本和许可证：MIT 之下，依赖才是关键
项目本身是 MIT 许可证，README 的 License 部分明确写了。但实际维护成本在依赖上。markitdown 和 repomix 都是独立项目，它们的更新节奏不受这里控制。你升级 markdownify-mcp 时，可能会发现 markitdown 的行为变了，或者 Python 虚拟环境需要重建。另一个成本是 Python 环境管理：preinstall 创建 .venv，但如果系统 Python 版本变化，可能需要手动清理重建。对于只想快速跑起来的用户，这些步骤可能显得繁琐，但 README 提供了足够的覆盖变量来绕过默认行为。
编辑结论
markdownify-mcp 适合已经使用 MCP 客户端（如桌面应用或 Docker 部署）且需要把多格式内容统一转为 Markdown 的工程师。它不适合对音频转写和图片 OCR 有硬性要求却只打算用 Docker 镜像的用户，因为官方镜像只装 markitdown[pdf]，这两个工具会直接失败。也不适合需要处理任意路径文件的场景，除非你明确设置 MD_ALLOWED_PATHS 来划定边界。采用前先确认三件事：本地是否安装了 bun 和 Python 虚拟环境，目标文件是否在 MD_ALLOWED_PATHS 允许的目录内，以及音频和图片功能是否通过本地安装获得完整 extras。如果这些条件都满足，这个服务器能省去为每个文件类型单独写转换脚本的麻烦。最终判断：它是一个把 markitdown 能力包装成 MCP 工具的实用层，价值取决于你对 MCP 生态的依赖程度，而不是转换算法本身。
社区笔记