/ 目录 / 演练场 / markdownify-mcp
● 社区 zcaceres ⚡ 即开即用

markdownify-mcp

作者 zcaceres · zcaceres/markdownify-mcp

在聊天中将 PDF、Word 文档、电子表格、幻灯片、网页、图片、音频和 YouTube 视频转换为干净的 markdown。

zcaceres/markdownify-mcp 是一个 TypeScript MCP,它将转换工具(包括 Microsoft 的 markitdown 和 YouTube 字幕获取器)包装在统一的接口后面。非常适合作为 RAG 管道的数据源,也适合将遗留文档粘贴到 markdown 原生工作流中。

为什么要用

核心特性

实时演示

实际使用效果

markdownify.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "markdownify": {
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "markdownify",
      "command": "npx",
      "args": [
        "-y",
        "markdownify-mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "markdownify": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "markdownify-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add markdownify -- npx -y markdownify-mcp

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: markdownify-mcp

如何将 PDF 文件夹摄取到 markdown 知识库中

👤 RAG 构建者、知识管理者 ⏱ ~30 min intermediate

何时使用: 你有 50 份 PDF 研究论文,想要干净的文本来嵌入。

前置条件
  • pnpm — npm i -g pnpm
  • 安装并运行 — git clone 项目,pnpm install,pnpm start
步骤
  1. 列举文件
    列出 /library/papers/ 下的所有 .pdf 文件。✓ 已复制
    → 路径列表
  2. 批量转换
    对于每个文件,调用 pdf-to-markdown。将输出写入 /library/markdown/<同名>.md。✓ 已复制
    → markdown 文件出现
  3. 随机抽查一个
    显示 /library/markdown/attention-is-all-you-need.md 的前 500 个字符。✓ 已复制
    → 清晰的 markdown,没有 PDF 伪影

结果: 一个并行的 /markdown/ 树,准备好嵌入。

注意事项
  • 扫描 PDF(仅图像)生成空 markdown — 在转换前对扫描的 PDF 进行 OCR
  • 数学丰富的 PDF 会丢失方程 — 对于数学内容,尝试配合 Mathpix 或单独使用 nougat OCR 模型
搭配使用: filesystem

如何将会议录音转换为可搜索的笔记

👤 任何录制会议的人 ⏱ ~10 min beginner

何时使用: 通话后,趁记忆还新鲜的时候。

前置条件
  • Whisper 的 OpenAI 密钥 — platform.openai.com(或任何兼容 Whisper 的端点)
步骤
  1. 转录
    对 /recordings/2026-04-14-standup.m4a 调用 audio-to-markdown。✓ 已复制
    → 带时间戳的 markdown
  2. 提取行动项
    从转录中列出带负责人的行动项。✓ 已复制
    → 行动清单

结果: 可搜索的会议笔记 + 行动项。

注意事项
  • Whisper 错误标记发言人 — 对于说话者分离,使用专门工具;markdownify 只给你文本
搭配使用: notion

如何在不看视频的情况下总结 YouTube 视频

👤 研究人员、学习者 ⏱ ~5 min beginner

何时使用: 你有 90 分钟的视频但只有 5 分钟时间。

步骤
  1. 获取字幕
    对 https://youtu.be/xyz123 调用 youtube-to-markdown。✓ 已复制
    → 转录 markdown
  2. 总结
    总结为 5 个要点 + 关键时间戳。✓ 已复制
    → 带跳转点的项目符号总结

结果: 决定是否真的要看这个视频。

注意事项
  • 某些视频禁用了字幕 — 工具返回空 — 如果你有文件,回退到 audio-to-markdown

组合

与其他 MCP 搭配,撬动十倍杠杆

markdownify + filesystem

批量转换收件箱文件夹到知识库文件夹

将 /inbox/ 中的每个文件转换为 /kb/ 下的 markdown,保留目录结构。✓ 已复制
markdownify + notion

将转换后的文档直接放入 Notion

转换 PDF /specs/rfq-2026.pdf,并创建一个包含结果的 Notion 页面。✓ 已复制
markdownify + excel

将 xlsx-to-markdown 与 excel MCP 结合进行往返转换

读取 /report.xlsx 工作表 'Summary',转换为 markdown,并保存到 /docs/report.md。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
pdf-to-markdown path_or_url: str 转换 PDF free (local)
docx-to-markdown path_or_url: str Word 文档 free
xlsx-to-markdown path_or_url: str 电子表格作为表格 free
pptx-to-markdown path_or_url: str 幻灯片组 free
image-to-markdown path_or_url: str 图片 free or 1 LLM call if OCR enabled
audio-to-markdown path: str 音频/语音备忘录 1 Whisper call ($0.006/min)
youtube-to-markdown url: str YouTube 字幕 free
webpage-to-markdown url: str 可读的网页文本 free
bing-search-to-markdown query: str 快速网络搜索 free
get-markdown-file path: str 检索之前的转换 free

成本与限制

运行它的成本

API 配额
本地转换器无配额限制;音频使用 Whisper/OpenAI
每次调用 Token 数
取决于文档大小
费用
免费(音频转录除外,约 $0.006/分钟 via Whisper)
提示
对于大量 PDF 批处理,在粘贴到 LLM 前进行转换 — 比让 Claude 直接解析 PDF 便宜。

安全

权限、密钥、影响范围

最小权限: 源文件的文件系统读权限,输出的写权限
凭据存储: OPENAI_API_KEY(用于音频)在环境变量中
数据出站: 本地转换器保持本地。音频发送到你的 Whisper 端点。
切勿授予: 不要在没有沙盒的情况下通过 webpage-to-markdown 运行不受信任的 URL — SSRF 风险

故障排查

常见错误与修复

pnpm install 失败

Node 版本太旧 — 需要 Node 18+。nvm install 20。

验证: node -v
pdf-to-markdown 返回空字符串

可能是扫描 PDF(仅图像)。先运行 OCR (ocrmypdf)。

youtube-to-markdown '无字幕可用'

视频所有者禁用了字幕。下载音频并改用 audio-to-markdown。

audio-to-markdown 401

缺少或无效的 OPENAI_API_KEY。

验证: echo $OPENAI_API_KEY

替代方案

markdownify-mcp 对比其他方案

替代方案何时用它替代权衡
markitdown (Microsoft)你想直接使用底层转换器而不需要 MCP没有 MCP 接口;需要你自己包装
unstructured.io企业规模的摄取,具有布局感知高级功能需要付费

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills