Third-party toolUpdated 2026.11.21

Pandoc MCP on Windows: Connect Codex and Claude Code to Convert Markdown to Word

Connect Pandoc MCP to Codex and Claude Code on Windows. Convert Markdown to DOCX and HTML, check a Word round trip and fix missing output paths.

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 --version on this computer, then pass the resolved executable path through PYPANDOC_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.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Past issues

Or follow us on: