/ 目錄 / 演練場 / 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
  • Install + run — git clone the repo, 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

何時使用: 通話結束後、記憶消退之前。

前置條件
  • OpenAI key for Whisper — platform.openai.com (or any Whisper-compatible endpoint)
步驟
  1. 轉錄
    對 /recordings/2026-04-14-standup.m4a 執行 audio-to-markdown。✓ 已複製
    → 帶有時間戳記的 Markdown
  2. 提取待辦事項
    從逐字稿中列出含負責人的行動項目。✓ 已複製
    → 行動清單

結果: 可搜尋的會議記錄與行動清單。

注意事項
  • Whisper 可能誤判發言者 — 如需說話者分離,請使用專用工具;markdownify 僅提供文字內容
搭配使用: notion

如何不看影片就摘要 YouTube 內容

👤 研究人員、學習者 ⏱ ~5 min beginner

何時使用: 當你只有 5 分鐘,卻有一部 90 分鐘的影片在待看清單時。

步驟
  1. 擷取字幕
    對 https://youtu.be/xyz123 執行 youtube-to-markdown。✓ 已複製
    → 字幕 Markdown
  2. 摘要
    用 5 條重點加關鍵時間戳記進行摘要。✓ 已複製
    → 含跳轉點的條列式摘要

結果: 決定是否真的需要觀看這部影片。

注意事項
  • 部分影片已停用字幕 — 工具會回傳空白——若有影片檔案,改用 audio-to-markdown

組合

與其他 MCP 搭配,撬動十倍槓桿

markdownify + filesystem

批次將收件匣資料夾轉換至知識庫資料夾

將 /inbox/ 中的所有檔案轉換為 Markdown,輸出至 /kb/ 並保留目錄結構。✓ 已複製
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 數
取決於文件大小
費用
除音訊轉錄外免費(透過 Whisper 約 ~$0.006/分鐘)
提示
處理大量 PDF 時,先完成轉換再貼入 LLM——比直接請 Claude 解析 PDF 更省費用。

安全

權限、密鑰、影響範圍

最小權限: Filesystem read on source files, write on output
憑證儲存: OPENAI_API_KEY(音訊用)存放於環境變數
資料出站: 本機轉換器的資料不會外傳。音訊會傳送至你的 Whisper 端點。
切勿授予: Don't run untrusted URLs through webpage-to-markdown without sandboxing — SSRF risk

故障排查

常見錯誤與修復

pnpm install fails

Node 版本過舊——需要 Node 18 以上。請執行 nvm install 20。

驗證: node -v
pdf-to-markdown returns empty string

可能是掃描式 PDF(純圖片)。請先執行 OCR(ocrmypdf)。

youtube-to-markdown 'no captions available'

影片擁有者已停用字幕。請下載音訊後改用 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