mcp-pandoc: A Document Conversion MCP Server

Officially included in the Model Context Protocol servers open-source project. 🎉

Overview

Demo

🎥 Watch on YouTube

Tools

1. convert-contents

   • Transforms content between supported formats
   • Inputs:

     • contents

       (string): Source content to convert (required if input_file not provided)

     • input_file

       (string): Complete path to input file (required if contents not provided)

     • input_format

       (string): Source format of the content (defaults to markdown)

     • output_format

       (string): Target format (defaults to markdown)

     • output_file

       (string): Complete path for output file (required for pdf, docx, rst, latex, epub formats)
   • Supported input/output formats:
     • markdown
     • html
     • pdf
     • docx
     • rst
     • latex
     • epub
     • txt
   • Note: For advanced formats (pdf, docx, rst, latex, epub), an output_file path is required

Supported Formats

• Plain text (.txt)
• Markdown (.md)
• HTML (.html)

• PDF (.pdf) - requires TeX Live installation
• DOCX (.docx)
• RST (.rst)
• LaTeX (.tex)
• EPUB (.epub)

1. Complete file paths with filename and extension are required
2. PDF conversion requires TeX Live installation (see Critical Requirements section -> For macOS:

   brew install texlive

   )
3. When no output path is specified:
   • Basic formats: Displays converted content in the chat
   • Advanced formats: May save in system temp directory (/tmp/ on Unix systems)

Usage & configuration

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

⚠️ Important Notes

Critical Requirements

1. PDF Conversion Prerequisites
   • TeX Live must be installed before attempting PDF conversion
   • Installation commands:

     # 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/
     

2. File Path Requirements
   • When saving or converting files, you MUST provide complete file paths including filename and extension
   • The tool does not automatically generate filenames or extensions

Examples

# Converting content to PDF
"Convert this text to PDF and save as /path/to/document.pdf"

# Converting between file formats
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

# Missing filename and extension
"Save this as PDF in /documents/"

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /documents/story"

Common Issues and Solutions

1. PDF Conversion Fails
   • Error: "xelatex not found"
   • Solution: Install TeX Live first (see installation commands above)
2. File Conversion Fails
   • Error: "Invalid file path"
   • Solution: Provide complete path including filename and extension
   • Example:

     /path/to/document.pdf

     instead of just

     /path/to/

3. Format Conversion Fails
   • Error: "Unsupported format"
   • Solution: Use only supported formats:
     • Basic: txt, html, markdown
     • Advanced: pdf, docx, rst, latex, epub

Quickstart

Install

Option 1: Installing manually via claude_desktop_config.json config file

• On MacOS:

  open ~/Library/Application\ Support/Claude/claude_desktop_config.json

• On Windows:

  %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--directory",
      "<DIRECTORY>/mcp-pandoc",
      "run",
      "mcp-pandoc"
    ]
  }
}

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

Option 2: To install Published Servers Configuration automatically via Smithery

npx -y @smithery/cli install mcp-pandoc --client claude

Development

Building and Publishing

1. Sync dependencies and update lockfile:

uv sync

1. Build package distributions:

uv build

dist/

1. Publish to PyPI:

uv publish

• Token:

  --token

  or

  UV_PUBLISH_TOKEN

• Or username/password:

  --username

  /

  UV_PUBLISH_USERNAME

  and

  --password

  /

  UV_PUBLISH_PASSWORD

Debugging

npm

npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc

Contributing

1. Report Issues: Found a bug or have a feature request? Open an issue on our GitHub Issues page.
2. Submit Pull Requests: Improve the codebase or add features by creating a pull request.