📌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 Model Context Protocol servers open-source project.

Overview

A Model Context Protocol server for document format conversion using pandoc. This server provides tools to transform content between different document formats while preserving formatting and structure.

mcp-pandoc is currently in early development. PDF support is under development, and the functionality and available tools may change as the server improves.

This project uses the Pandoc Python package for document conversion.

Demo

🎥 Watch on YouTube

More demos to come.

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
For advanced formats (pdf, docx, rst, latex, epub), an output_file path is required.

Supported Formats

Currently supported formats:

Basic formats (direct conversion):

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

Advanced formats (require complete file paths):

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

Notes:

For advanced formats, provide complete file paths including filename and extension.
PDF conversion requires TeX Live installation.
When no output path is specified:
- Basic formats: converted content is displayed in the chat.
- Advanced formats: file may be saved in system temp directory (e.g., /tmp/ on Unix systems).

Usage & Configuration

To use the published server, add the following to your configuration:

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

Important Notes

Critical Requirements

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/

File Path Requirements
- Complete file paths including filename and extension must be provided for saving or converting files.
- Filenames and extensions are not auto-generated.

Usage Examples

Correct usage:

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

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

Incorrect usage:

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

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /documents/story"

Troubleshooting Common Issues

PDF Conversion Fails
- Error: "xelatex not found"
- Solution: Install TeX Live (see installation commands above).
File Conversion Fails
- Error: "Invalid file path"
- Solution: Provide complete file paths with filename and extension.
Format Conversion Fails
- Error: "Unsupported format"
- Solution: Use supported formats:
  - Basic: txt, html, markdown
  - Advanced: pdf, docx, rst, latex, epub

Quickstart

Install

Option 1: Manual configuration

Edit the claude_desktop_config.json file:

On macOS: open ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

For Published Servers Configuration:

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

For Development/Unpublished Servers Configuration:
Replace <DIRECTORY> with your local project path.

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

Option 2: Automatic installation via Smithery

Run this command to install the published mcp-pandoc server for Claude Desktop automatically:

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

Development

Building and Publishing

Sync dependencies and update lockfile:

uv sync

Build package distributions:

uv build

Publish to PyPI:

uv publish

Set PyPI credentials via environment variables or command flags:

Token: --token or UV_PUBLISH_TOKEN
Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. It is recommended to use the MCP Inspector.

Launch the MCP Inspector using npm:

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

The Inspector will provide a URL to open in a browser for debugging.

Contributing

Contributions are welcome!

Report issues or feature requests on GitHub Issues.
Submit pull requests to improve or add features.