📌Overview

Purpose: To provide a server for converting documents between various formats using the Pandoc tool, while ensuring formatting and structure are maintained.

Overview: The mcp-pandoc server is part of the Model Context Protocol open-source project and utilizes the Pandoc Python package for efficient document format conversions. It is in early development, with ongoing enhancements such as PDF support.

Key Features:

• Versatile Format Conversion: Supports a wide array of document formats including plaintext, Markdown, HTML, PDF, DOCX, RST, LaTeX, and EPUB, facilitating seamless conversion across different types of documents.

• Content Transformation Tools: Offers a robust API method convert-contents that allows users to either input raw content or specify files for conversion, enhancing usability and flexibility in document processing.

---

mcp-pandoc: A Document Conversion MCP Server

Officially included in the 1 open-source project. 🎉

Overview

mcp-pandoc is a Model Context Protocol server for document format conversion using pandoc. This server allows you to transform content between various document formats while preserving formatting and structure.

Currently, mcp-pandoc is in early development, with PDF support underway. The available tools and functionalities will continue to evolve.

Credit: This project utilizes the Pandoc Python package for document conversion.

Tools

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

Supported Formats

Basic Formats (Direct Conversion):

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

Advanced Formats (Requires Complete File Paths):

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

Note: For advanced formats:

1. Complete file paths with filename and extension are required.
2. PDF conversion requires TeX Live installation.

Usage & Configuration

To use the published server, include the following in your 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
   

2. File Path Requirements

   • Provide complete file paths including filename and extension when saving or converting files.

Common Issues and Solutions

1. PDF Conversion Fails:

   • Solution: Install TeX Live.

2. File Conversion Fails:

   • Solution: Provide a complete path including filename and extension.

3. Format Conversion Fails:

   • Solution: Use only supported formats.

Quickstart

Install

Option 1: Manual Installation via Configuration File

Edit the claude_desktop_config.json file:

• MacOS: open ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Option 2: Automatic Installation via Smithery

Run the following command to install published mcp-pandoc pypi:

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

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies:

   uv sync
   

2. Build package distributions:

   uv build
   

3. Publish to PyPI:

   uv publish
   

Debugging

MCP servers run over stdio; for debugging, we recommend using the MCP Inspector.

Launch the MCP Inspector with:

npx @modelcontextprotocol/inspector uv --directory /path/to/your/directory run mcp-pandoc

Contributing

We welcome contributions to enhance mcp-pandoc! Here's how you can get involved:

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