mcp-pandoc is a Model Context Protocol (MCP) server for document format conversion, implemented on the basis of Pandoc. This project has been officially included in the Model Context Protocol open-source server project. It should be noted that mcp-pandoc is currently in an early development stage, PDF support is still under development, and its features and available tools may change or expand with continuous improvements. The project uses the Pandoc Python package for document conversion, which is the foundation of the entire project.
Purpose
This server provides tools for converting content between different document formats, preserving formatting and structure as much as possible during conversion. It is suitable for development, writing, and workflow scenarios that require automated document format conversion.
Main capabilities
The core tool convert-contents can convert content between supported formats.
Input parameters include:
- contents (string): the source content to be converted (required when input_file is not provided)
- input_file (string): the full path to the input file (required when contents is not provided)
- input_format (string): the source format, defaults to markdown
- output_format (string): the target format, defaults to markdown
- output_file (string): the full path to the output file (required for pdf, docx, rst, latex, epub, odt, pptx formats)
- reference_doc (string): the path to the reference document used for styling (supports docx, odt, and pptx output; the file must match the output format)
- defaults_file (string): the path to a Pandoc defaults file (YAML) containing conversion options
- filters (array): a list of paths to Pandoc filters applied during conversion
Supported formats and directions:
- markdown: readable and writable
- html: readable and writable
- docx: readable and writable
- odt: readable and writable
- rst: readable and writable
- latex: readable and writable
- epub: readable and writable
- ipynb: readable and writable
- txt: readable and writable
- pdf: not readable, writable
- pptx: not readable, writable
Note: For pdf, docx,rst, latex, epub, odt, pptx and other advanced formats, an output_file path must be provided. PDF and PPTX are write-only formats: Pandoc has never provided a PDF reader; Pandoc added a PowerPoint reader in version 3.8.3 (released 2025-12-01), but this project does not declare a minimum Pandoc version, and Ubuntu 24.04 still ships with Pandoc 3.1.3, so pptx input is not provided. PPTX output does not require a specific Pandoc version; the PowerPoint writer has existed since Pandoc 2.0.5.
Advanced features
A defaults file can be used to create reusable conversion templates with consistent formatting, for example: "Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf". Custom filters can be applied for enhanced processing, for example: "Convert docs.md to HTML with filters ['/path/to/mermaid-filter.py'] and save as docs.html". For more examples and workflows, see CHEATSHEET.md.
Usage and configuration
The required packages listed below must be installed before use.
Pandoc installation (required, the core document conversion engine):
- macOS: brew install pandoc
- Ubuntu/Debian: sudo apt-get install pandoc
- Windows: from https://pandoc.org/installing.html download the installer
- Verify: pandoc --version
UV package installation (required, includes the uvx command):
- macOS: brew install uv
- Windows/Linux: pip install uv
- Verify: uvx --version
Prerequisites for PDF conversion (only when PDF conversion and saving are needed): TeX Live must be installed first.
- Ubuntu/Debian: sudo apt-get install texlive-xetex
- macOS: brew install texlive
- Windows: from https://miktex.org/ or https://tug.org/texlive/ Install MiKTeX or TeX Live
File path requirements: When saving or converting files, you must provide a complete file path including the file name and extension. The tool will not automatically generate a file name or extension. If no output path is specified: basic formats will display the converted content in the chat; advanced formats may be saved in the system temporary directory (/tmp/ on Unix systems).
Manual configuration: It can be installed via the claude_desktop_config.json configuration file.
- macOS: Open ~/Library/Application\ Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json There are two configuration cases: a) for local development only and contributing to this repository (you need to replace it with the path of the locally cloned project); b) configuration for the published server, which users should use. If you encounter problems, please use the "published server configuration" directly rather than the CLI. To configure mcp-pandoc locally, follow the "development/unpublished server configuration" steps.
Use cases
Suitable for scenarios that require document conversion between formats such as Markdown, HTML, DOCX, ODT, RST, LaTeX, EPUB, IPYNB, and TXT; scenarios that require applying a unified style template or custom filters during conversion; and developers and writers who need to integrate the conversion process into an MCP client workflow.
Limitations and notes
- The project is in an early development stage, and features and tools may change.
- PDF and PPTX support output only and cannot be read as input.
- Advanced formats must provide a complete output_file path.
- reference_doc only supports DOCX, ODT, and PPTX output, and the reference document must match the output format. Pandoc itself does not check this: for DOCX output, a mismatched reference document is silently ignored; for ODT output, it produces an ODT file that cannot be opened. How to create a reference document: pandoc -o reference.docx --print-default-data-file reference.docx, reference.odt or reference.pptx likewise.
- Common errors and solutions: PDF conversion reports "xelatex not found", so TeX Live must be installed first; file conversion reports "Invalid file path", so you must provide a complete path including the file name and extension, for example /path/to/document.pdf rather than only /path/to/; format conversion reports "Unsupported format", so you must use only supported formats; reference document reports "Reference document not found", so you must ensure that the reference document path exists and is accessible.
- Because the MCP server runs via stdio, debugging may be difficult, and using MCP Inspector for debugging is recommended. MCP Inspector can be started via an npm command, and after startup it displays a URL that can be accessed in a browser to begin debugging.
The project welcomes contributions: you can report issues or submit feature requests on the GitHub Issues page; you can also improve the codebase or add features by creating a pull request.
