# vivekvells/mcp-pandoc [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/vivekVells/mcp-pandoc  
**GitHub Stars:** 584  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/vivekvells-mcp-pandoc

## Description
MCP server for seamless document format conversion using Pandoc, supporting Markdown, HTML, PDF, DOCX (.docx), csv and more.

## Tools
Capabilities this server exposes over MCP:

- **convert-contents** — Converts content between different formats. Transforms input content from any supported format into the specified output format.

🚨 CRITICAL REQUIREMENTS - PLEASE READ:
1. PDF Conversion:
   * You MUST install TeX Live BEFORE attempting PDF conversion:
   * Ubuntu/Debian: `sudo apt-get install texlive-xetex`
   * macOS: `brew install texlive`
   * Windows: Install MiKTeX or TeX Live from https://miktex.org/ or https://tug.org/texlive/
   * PDF conversion will FAIL without this installation

2. File Paths - EXPLICIT REQUIREMENTS:
   * When asked to save or convert to a file, you MUST provide:
     - Complete directory path
     - Filename
     - File extension
   * Example request: 'Write a story and save as PDF'
   * You MUST specify: '/path/to/story.pdf' or 'C:\Documents\story.pdf'
   * The tool will NOT automatically generate filenames or extensions

3. File Location After Conversion:
   * After successful conversion, the tool will display the exact path where the file is saved
   * Look for message: 'Content successfully converted and saved to: [file_path]'
   * You can find your converted file at the specified location
   * If no path is specified, files may be saved in system temp directory (/tmp/ on Unix systems)
   * For better control, always provide explicit output file paths

Supported formats:
- Basic (returned inline): txt, html, markdown, ipynb
- Advanced (REQUIRE complete file paths): pdf, docx, rst, latex, epub, odt, pptx
- pptx is WRITE-ONLY: it can be produced, but not used as an input format
✅ CORRECT Usage Examples:
1. 'Convert this text to HTML' (basic conversion)
   - Tool will show converted content

2. 'Save this text as PDF at /documents/story.pdf'
   - Correct: specifies path + filename + extension
   - Tool will show: 'Content successfully converted and saved to: /documents/story.pdf'

❌ INCORRECT Usage Examples:
1. 'Save this as PDF in /documents/'
   - Missing filename and extension
2. 'Convert to PDF'
   - Missing complete file path

When requesting conversion, ALWAYS specify:
1. The content or input file
2. The desired output format
3. For advanced formats: complete output path + filename + extension
Example: 'Convert this markdown to PDF and save as /path/to/output.pdf'

🎨 DOCX, ODT & PPTX STYLING:
4. Custom Styling with Reference Documents:
   * Use reference_doc parameter to apply professional styling to DOCX, ODT and PPTX output
   * The reference document MUST match the output format: .docx for docx, .odt for odt,
     .pptx for pptx
   * Create custom templates with your branding, fonts, and formatting
   * Perfect for corporate reports, academic papers, and professional documents
   * Example: 'Convert this report to DOCX using /templates/corporate-style.docx as reference and save as /reports/Q4-report.docx'

🎯 PANDOC FILTERS (NEW FEATURE):
5. Pandoc Filter Support:
   * Use filters parameter to apply custom Pandoc filters during conversion
   * Filters are Python scripts that modify document content during processing
   * Perfect for Mermaid diagram conversion, custom styling, and content transformation
   * Example: 'Convert this markdown with mermaid diagrams to DOCX using filters=["./filters/mermaid-to-png-vibrant.py"] and save as /reports/diagram-report.docx'

📋 Creating Reference Documents:
   * Generate template: pandoc -o template.docx --print-default-data-file reference.docx
   * Customize in Word/LibreOffice: fonts, colors, headers, margins
   * Use for consistent branding across all documents

📋 Filter Requirements:
   * Filters must be executable Python scripts
   * Use absolute paths or paths relative to current working directory
   * Filters are applied in the order specified
   * Common filters: mermaid conversion, color processing, table formatting

📄 Defaults File Support (NEW FEATURE):
7. Pandoc Defaults File Support:
   * Use defaults_file parameter to specify a YAML configuration file
   * Similar to using pandoc -d option in the command line
   * Allows setting multiple options in a single file
   * Options in the defaults file can include filters, reference-doc, and other Pandoc options
   * Example: 'Convert this markdown to DOCX using defaults_file="/path/to/defaults.yaml" and save as /reports/report.docx'

Note: After conversion, always check the success message for the exact file location.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-pandoc": {
    "command": "uvx",
    "args": ["mcp-pandoc"]
  }
}
```

## Documentation

## What vivekvells/mcp-pandoc MCP server does

vivekvells/mcp-pandoc MCP server connects an MCP client to Pandoc for document format conversion. The conversion tool can work from raw text supplied in `contents` or from a complete input-file path. Callers specify the source and destination formats, with Markdown used as the default input and output format when those values are not provided.

The server supports reading and writing Markdown, HTML, DOCX, ODT, RST, LaTeX, EPUB, IPYNB, and TXT. PDF and PPTX are write-only in the documented interface: the server can produce them but does not accept them as input. Basic-format results can be returned inline, while advanced output formats require an output path according to the tool documentation.

## How it works

The MCP tool named `convert-contents` receives conversion parameters and passes the work to Pandoc through the project’s Python package foundation. Its inputs include `contents`, `input_file`, `input_format`, `output_format`, `output_file`, `reference_doc`, `defaults_file`, and `filters`.

Use `reference_doc` when generating DOCX, ODT, or PPTX and applying styles from a template. The reference document must use the same format as the requested output. A YAML defaults file can hold reusable Pandoc options such as metadata, a table of contents, or section numbering. Filter paths can also be supplied as an array for custom processing.

## Setup and configuration

The published package can be launched with `uvx mcp-pandoc` in an MCP client configuration. The server itself does not document credential or API-key configuration. Pandoc must be installed separately because it is the conversion engine. PDF output additionally requires a TeX Live installation.

A typical MCP configuration uses the `uvx` command with `mcp-pandoc` as its argument. Input and output paths should be complete paths with filenames and extensions when working with advanced formats. If an advanced conversion has no output path, the documentation notes that a temporary system path may be used.

## Tools and capabilities

The documented conversion inputs provide these capabilities:

- Convert inline content or a file between supported formats.
- Select source and target formats explicitly.
- Write DOCX, ODT, PDF, PPTX, RST, LaTeX, and EPUB results to files.
- Apply a matching reference document for DOCX, ODT, and PPTX styling.
- Reuse conversion settings from a Pandoc YAML defaults file.
- Run specified Pandoc filters during conversion.

## Limitations and notes

PDF cannot be read by Pandoc and is available only as an output format here. PPTX input is also not offered by this project, while PPTX output is supported. PDF generation depends on TeX Live, and the README identifies PDF support as still under development. The project is described as early development, so available behavior and tools may change.

Its format support therefore also depends on the installed Pandoc environment and the requirements of the requested output format.

_Full upstream README: https://allmcps.com/mcp/vivekvells-mcp-pandoc/readme_