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,查閱日期同上。