mcp-pandoc gives an assistant access to Pandoc's document conversions. Use it when a Markdown report needs to become a DOCX deliverable, or when Word content needs to return to editable text. It is a converter rather than a page-layout editor or PDF extractor. Installation has two distinct parts: the Pandoc executable and the MCP server that exposes it to the assistant.
Install both parts
Prepare Pandoc using the official installation guide and confirm pandoc --version works. With uv and Python 3.12 available, run this in a fresh PowerShell directory:
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
After Connected appears, start a fresh session. Codex:
codex mcp add pandoc --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 --env "PYPANDOC_PANDOC=$pandoc" -- $server
codex mcp list
The executable path in PYPANDOC_PANDOC avoids depending on the client's PATH. Codex stores its registration at user level. For Cursor, follow the upstream stdio configuration with the same executable and three environment variables under mcpServers in .cursor/mcp.json; see Cursor's MCP reference for the client format.
Create a small report
Save this as UTF-8 brief.md:
# 每週銷售
| Region | Amount |
|---|---:|
| Taipei | 200 |
| Kaohsiung | 50 |
Deliver a Word file
Use only pandoc MCP convert-contents. Convert brief.md from markdown
to docx as brief.docx in this directory. Supply full input_file and
output_file paths and return the resulting location.
The tool should report File successfully converted and saved to:. Our saved DOCX retained the Chinese heading and a real table containing both cities and amounts.
Bring Word content back into Markdown
Convert that brief.docx from docx to markdown and return the content
inline. Check the heading, Taipei 200 and Kaohsiung 50.
Do not assume the Markdown source formatting will be identical.
Pandoc returned a plain-text-style table rather than the original pipe-table syntax. Compare content and structure separately from source spelling; a successful round trip is not a byte-for-byte restoration.
Produce an HTML fragment
Convert brief.md from markdown to html, returning the result inline.
Check for h1 and table elements with both city/amount rows.
Do not upload or publish anything.
The returned fragment contained <h1> and <table> elements. It can feed an existing website or document pipeline; a standalone HTML page is a separate output choice.
Troubleshooting
output_file path is required for docx format: we received this exact error when the output path was omitted. Supply the complete filename and extension for file-based outputs.- The MCP package is installed but Pandoc is missing: the Python package and converter executable are separate dependencies. Confirm
pandoc --versionon this computer, then pass the resolved executable path throughPYPANDOC_PANDOC. - PDF export cannot find a LaTeX engine: the demonstrated DOCX route does not require TeX. PDF has additional engine choices explained in Pandoc's PDF guide.
- A directory claims an API key is necessary: package-publishing tokens belong to the maintainer's release process. They are not credentials required to convert your files locally.
Cost, licensing and limits
mcp-pandoc is MIT licensed; Pandoc is GPL licensed. Local conversion has no per-request service fee or account requirement, while AI-client usage remains separate. The server accepts full filesystem paths and this setup does not add a directory sandbox. Practice on copies and inspect the output before delivery.
Do not expect automatic preservation of complex page layout. Templates, fonts, images and pagination need their own checks. Nor does a PDF value appearing in a parameter list make Pandoc a PDF reader. For PDF extraction, see PyMuPDF4LLM; for extracting content from several document formats, see MarkItDown.
FAQ
Does installing Pandoc make it a Claude Code tool?
No. Pandoc is an executable; mcp-pandoc is the server that exposes conversion to an MCP client. Prepare both and register the server before expecting convert-contents in an assistant session.
Is Word conversion offline?
Once installed, this local text-and-table conversion requires no external conversion service. Your AI client may still contact its model provider. Documents containing remote images or custom filters introduce separate dependencies.
Why did the table change when converting back to Markdown?
The same table can be serialized in several Markdown forms. Check rows, columns and content before comparing source appearance. Our two city/amount rows survived, although the pipe-table syntax did not.
What we tested
2026-11-16: Windows, Python 3.12, mcp-pandoc 0.11.1 and Pandoc 3.8. Real Codex MCP conversions in all three demonstrated directions, a missing-output-path error and independent DOCX heading/table checks. Claude Code registration reported Connected. Cursor, PDF/TeX, images and pagination were not tested. Configuration and format directions: upstream README, accessed the same day.