第三方工具更新 2026.11.21

Pandoc MCP 教學:Windows 接 Claude Code、Codex,把 Markdown 轉成 Word

Windows安裝Pandoc MCP並設定Claude Code、Codex,真正把Markdown轉成Word及HTML。附完整路徑、回轉表格差異與PDF引擎排錯。

mcp-pandoc 把 Pandoc 轉檔能力交給 AI,適合把 Markdown 報告交成 DOCX,或把 Word 內容轉回可編輯的文字。它是轉檔器,不是 Word 版面編輯器,也不是 PDF 文字擷取工具。這篇把兩個常被混在一起的安裝拆清楚:電腦需要 Pandoc 執行檔,AI 還需要 MCP 伺服器。

安裝與 Windows 路徑

先從 Pandoc 官方安裝說明準備 Pandoc,並確認 pandoc --version 可執行;另外需要 uv 與 Python 3.12。在新資料夾用 PowerShell:

uv venv --python 3.12 .venv
uv pip install --python .\.venv\Scripts\python.exe mcp-pandoc==0.11.1
$server = (Resolve-Path .\.venv\Scripts\mcp-pandoc.exe).Path
$pandoc = (Get-Command pandoc.exe).Source

Claude Code:

claude.cmd mcp add pandoc --scope project --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 --env "PYPANDOC_PANDOC=$pandoc" -- $server
claude.cmd mcp list

確認 Connected,再開啟新的工作階段。Codex:

codex mcp add pandoc --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 --env "PYPANDOC_PANDOC=$pandoc" -- $server
codex mcp list

PYPANDOC_PANDOC 指定真正的轉檔程式,避免 AI 客戶端的 PATH 和終端機不同。Codex 註冊保存在使用者設定。Cursor 的上游設定同樣使用 stdio;在 .cursor/mcp.json 的 mcpServers 指定此執行檔和三個環境變數即可,格式見 Cursor MCP 文件。

準備報告

把以下存成 UTF-8 的 brief.md:

# 每週銷售

| Region | Amount |
|---|---:|
| Taipei | 200 |
| Kaohsiung | 50 |

用途一:交出 Word 檔案

只用 pandoc MCP 的 convert-contents,把目前資料夾 brief.md
從 markdown 轉為 docx,存成同資料夾 brief.docx。
input_file與output_file都使用完整路徑,完成後回報輸出位置。

工具應回覆 File successfully converted and saved to:。我們檢查 DOCX,標題「每週銷售」與兩筆城市/金額都保留在真正的 Word 表格裡。

用途二:把 Word 轉回文字整理

把剛產生的brief.docx,以convert-contents從docx轉回markdown,直接回傳內容。
核對標題、Taipei 200、Kaohsiung 50;不要宣稱轉回的原始碼格式完全相同。

本例的表格回來是 Pandoc 的一般文字表格形式,不再是原本的管線表格語法。內容與原始 Markdown 排版語法要分開檢查;轉回成功不是逐位元相同。

用途三:產生 HTML 片段

將brief.md從markdown轉成html,直接回傳結果。
確認有h1、table,以及兩個城市和金額;不要自行發布或上傳。

這次會回傳 <h1> 和 <table> 片段,適合接進既有網站或文件流程;是否需要完整 HTML 頁面,應由你的後續程式決定。

常見錯誤

  • output_file path is required for docx format: 我們省略路徑時取得這個原始錯誤。DOCX 等檔案輸出必須指定完整檔名與副檔名;它不會替你猜輸出位置。
  • 已裝 MCP,仍找不到 Pandoc: pip 套件和 Pandoc 執行檔是不同依賴。先在同一台電腦執行 pandoc --version,再把解析出的 .exe 路徑交給 PYPANDOC_PANDOC。
  • PDF 匯出找不到 LaTeX 引擎: DOCX 轉檔不需要 TeX;PDF 的預設路線有額外引擎需求,請依官方 PDF 說明選擇。不要為了交 Word,先安裝整套 TeX。
  • 看見發布 token 就以為需要 API key: 上游維護者發布套件的憑證不是使用者的轉檔需求。本機 Pandoc 路線不需外部服務 key。

限制、授權與選擇

mcp-pandoc 採 MIT 授權;Pandoc 採 GPL 授權。本機轉檔沒有按次服務費,也不需帳戶,AI 客戶端用量另計。這個伺服器可以依完整路徑讀寫檔案,沒有本例另外設定的目錄沙箱。以副本練習,檢查輸出後再交付。

複雜排版不會靠轉檔自動重現。Word 範本、字型、圖片與頁面需要另行驗證;PDF 也不能因為出現在某個參數清單,就當作可讀取的輸入格式。要讀 PDF 可看 PyMuPDF4LLM;要從多種格式整理內容,可看 MarkItDown。

FAQ

裝 Pandoc 就會出現在 Claude Code 的工具裡嗎?

不會。Pandoc 是本機命令列程式;mcp-pandoc 才是把轉檔操作提供給 AI 的伺服器。兩者都準備好並完成 MCP 設定,工作階段才會看到 convert-contents。

可以完全離線轉成 Word 嗎?

套件與 Pandoc 安裝完成後,這個只有本機文字與表格的 DOCX 轉檔不需要外部轉檔服務。AI 客戶端如何連接模型是另一層;本機轉檔不表示整個 AI 對話離線。含遠端圖片、篩選器等來源的文件也要另外評估。

Word 轉回 Markdown,表格為什麼變樣?

Pandoc 可以把同一張表輸出為不同 Markdown 表格語法。先核對列、欄與內容,再決定是否需要固定輸出方言;不要直接比較兩段原始碼的外觀。本例保留兩個城市與金額,但表格語法確實改變。

我們測了什麼

2026-11-16:Windows、Python 3.12、mcp-pandoc 0.11.1、Pandoc 3.8。Codex 真完成 Markdown→DOCX、DOCX→Markdown、Markdown→HTML及省略輸出路徑的錯誤;另外檢查 DOCX 標題與三列表格。Claude Code 完成註冊與 Connected。Cursor、PDF/TeX、圖片與逐頁版面未測。設定及格式方向參考上游 README,查閱日期同上。

訂閱 AI 工具精選與使用建議

有值得推薦的新工具、實測發現或重要更新時,寄到你的信箱。

訂閱後先寄給你一份每月更新的 AI 工具與 Skill 清單。有值得推薦的工具、實測發現或重要更新時才寄信,隨時可以退訂。隱私權說明

快完成了,請到信箱收確認信點信裡的按鈕確認訂閱,就會收到工具清單的下載連結。沒看到的話,看一下垃圾郵件或「促銷內容」分頁。

看過去幾期

也可以在這些平台追蹤: