Conversion MCP Server

A powerful Model Context Protocol (MCP) server for converting documents between different formats, built with TypeScript and designed for Claude Desktop and other MCP clients.

🎯 Features

• 🔄 HTML to PDF: Convert HTML content or web pages to PDF format

• 📝 Markdown to HTML: Transform Markdown content to HTML with full styling

• 📄 Markdown to PDF: Direct conversion from Markdown to PDF with custom styling

• 📋 HTML to DOCX: Convert HTML content to Microsoft Word format

• 📑 Markdown to DOCX: Transform Markdown directly to DOCX with formatting

• 🌐 URL to PDF/DOCX: Convert any web page URL directly to PDF or DOCX

• 📁 File Conversions: Batch process HTML and Markdown files to multiple formats

• 🛡️ Security: Built-in HTML sanitization for untrusted content

• ⚡ Fast: Uses latest Puppeteer (v24.19.0), Marked (v16.2.1), and html-docx-js

• 🎨 Customizable: Full control over PDF/DOCX options, margins, formats, and styling

• 📦 TypeScript: Complete type safety and modern JavaScript features

• 🚀 Production Ready: Optimized for headless environments and CI/CD

Related MCP server: Claude Document MCP Server

🔧 Available Tools

html_to_pdf

Convert HTML content to PDF format with customizable options.

Input:

• html (string): HTML content to convert

• output_path (string): Full path where PDF should be saved

• options (object, optional): PDF generation options

  • format: Paper format (A4, A3, Letter, etc.)

  • landscape: Portrait or landscape orientation

  • printBackground: Include background graphics

  • scale: Webpage rendering scale (0.1-2)

  • margin: Custom margins (top, right, bottom, left)

Example:

{
  "html": "<h1>Hello World</h1><p>This is a test document.</p>",
  "output_path": "/Users/username/Documents/output.pdf",
  "options": {
    "format": "A4",
    "landscape": false,
    "printBackground": true,
    "margin": {
      "top": "2cm",
      "right": "1cm",
      "bottom": "2cm",
      "left": "1cm"
    }
  }
}

url_to_pdf

Convert any web page URL directly to PDF format.

Input:

• url (string): URL of the web page to convert

• output_path (string): Full path where PDF should be saved

• options (object, optional): Same PDF options as html_to_pdf

Example:

{
  "url": "https://example.com",
  "output_path": "/Users/username/Documents/webpage.pdf",
  "options": {
    "format": "A4",
    "printBackground": true
  }
}

markdown_to_html

Convert Markdown content to HTML format with optional sanitization.

Input:

• markdown (string): Markdown content to convert

• output_path (string, optional): Path to save HTML file (if not provided, returns HTML content)

• options (object, optional): Conversion options

  • sanitize: Remove potentially dangerous HTML (default: false)

  • fullDocument: Create complete HTML document with CSS (default: false)

  • title: Document title for full documents

  • gfm: Use GitHub Flavored Markdown (default: true)

  • breaks: Convert single line breaks to <br> (default: false)

Example:

{
  "markdown": "# Hello World\n\nThis is **bold** text.",
  "output_path": "/Users/username/Documents/output.html",
  "options": {
    "fullDocument": true,
    "title": "My Document",
    "sanitize": false,
    "gfm": true
  }
}

markdown_to_pdf

Convert Markdown content directly to PDF format.

Input:

• markdown (string): Markdown content to convert

• output_path (string): Full path where PDF should be saved

• options (object, optional): Combined Markdown and PDF options

  • title: Document title

  • sanitize: Sanitize HTML output (default: false)

  • format: Paper format (default: A4)

  • landscape: Orientation (default: false)

  • printBackground: Include backgrounds (default: true)

  • gfm: Use GitHub Flavored Markdown (default: true)

  • breaks: Convert line breaks (default: false)

Example:

{
  "markdown": "# My Report\n\n## Introduction\n\nThis is a **sample** report with *emphasis*.",
  "output_path": "/Users/username/Documents/report.pdf",
  "options": {
    "title": "Monthly Report",
    "format": "A4",
    "landscape": false,
    "sanitize": false
  }
}

html_to_docx

Convert HTML content to DOCX format with customizable options.

Input:

• html (string): HTML content to convert

• output_path (string): Full path where DOCX should be saved

• options (object, optional): DOCX generation options

  • orientation: Page orientation (portrait, landscape)

  • margins: Custom margins in twips (1440 = 1 inch)

    • top, right, bottom, left: Page margins

    • header, footer, gutter: Additional margin options

  • title: Document title

  • subject: Document subject

  • creator: Document creator/author

  • keywords: Document keywords

  • description: Document description

Example:

{
  "html": "<h1>Hello World</h1><p>This is a test document with <strong>bold</strong> text.</p>",
  "output_path": "/Users/username/Documents/output.docx",
  "options": {
    "orientation": "portrait",
    "title": "My Document",
    "creator": "John Doe",
    "margins": {
      "top": 1440,
      "right": 1440,
      "bottom": 1440,
      "left": 1440
    }
  }
}

markdown_to_docx

Convert Markdown content directly to DOCX format.

Input:

• markdown (string): Markdown content to convert

• output_path (string): Full path where DOCX should be saved

• options (object, optional): Combined Markdown and DOCX options

  • title: Document title

  • orientation: Page orientation (portrait, landscape)

  • margins: Custom margins in twips

  • gfm: Use GitHub Flavored Markdown (default: true)

  • breaks: Convert single line breaks to <br> (default: false)

  • sanitize: Sanitize HTML output (default: false)

  • fullDocument: Create full HTML document with CSS (default: true)

  • subject: Document subject

  • creator: Document creator/author

  • keywords: Document keywords

  • description: Document description

Example:

{
  "markdown": "# My Report\n\n## Summary\n\nThis is a **sample** report with *emphasis*.\n\n- Item 1\n- Item 2\n- Item 3",
  "output_path": "/Users/username/Documents/report.docx",
  "options": {
    "title": "Monthly Report",
    "creator": "Jane Smith",
    "orientation": "portrait",
    "gfm": true,
    "fullDocument": true
  }
}

file_to_pdf

Convert HTML or Markdown files to PDF format.

Input:

• input_path (string): Path to input file (.html, .htm, .md, .markdown)

• output_path (string): Full path where PDF should be saved

• options (object, optional): Format-specific conversion options

Example:

{
  "input_path": "/Users/username/Documents/input.md",
  "output_path": "/Users/username/Documents/output.pdf",
  "options": {
    "title": "Converted Document",
    "format": "A4",
    "printBackground": true
  }
}

file_to_docx

Convert HTML or Markdown files to DOCX format.

Input:

• input_path (string): Path to input file (.html, .htm, .md, .markdown)

• output_path (string): Full path where DOCX should be saved

• options (object, optional): Format-specific conversion options

  • title: Document title (auto-generated from filename if not provided)

  • orientation: Page orientation (portrait, landscape)

  • margins: Custom margins in twips

  • sanitize: Sanitize HTML output (default: false)

  • creator: Document creator/author

Example:

{
  "input_path": "/Users/username/Documents/input.md",
  "output_path": "/Users/username/Documents/output.docx",
  "options": {
    "title": "Converted Document",
    "orientation": "portrait",
    "creator": "Document Converter"
  }
}

📋 Prerequisites

• Node.js v18.0.0 or higher

• npm or yarn package manager

• MCP client (e.g., Claude Desktop)

🚀 Quick Start

Option 1: NPX (Recommended)

Run directly without installation:

# Show help information
npx conversion-mcp-server help

# Direct file conversion
npx conversion-mcp-server convert md-to-html readme.md readme.html
npx conversion-mcp-server convert md-to-pdf report.md report.pdf
npx conversion-mcp-server convert html-to-pdf page.html page.pdf

For Claude Desktop Integration:

1. Find your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add server configuration:

   {
     "mcpServers": {
       "conversion-server": {
         "command": "npx",
         "args": ["conversion-mcp-server"]
       }
     }
   }

3. Restart Claude Desktop

Option 2: Manual Installation

Clone and build locally:

git clone https://github.com/yokowasis/conversion-mcp-server.git
cd conversion-mcp-server
npm install
npm run build

For Claude Desktop with local installation:

{
  "mcpServers": {
    "conversion-server": {
      "command": "node",
      "args": ["/path/to/your/conversion-mcp-server/dist/index.js"]
    }
  }
}

🖥️ CLI Usage

Direct File Conversion

Convert files directly using the CLI without starting a server:

# Markdown to HTML conversion
npx conversion-mcp-server convert md-to-html input.md output.html
npx conversion-mcp-server convert md-to-html input.md output.html --full-doc --title "My Document"

# Markdown to PDF conversion  
npx conversion-mcp-server convert md-to-pdf report.md report.pdf --title "Monthly Report"

# HTML to PDF conversion
npx conversion-mcp-server convert html-to-pdf page.html page.pdf

# Markdown to DOCX conversion
npx conversion-mcp-server convert md-to-docx notes.md notes.docx --title "Meeting Notes"

# HTML to DOCX conversion
npx conversion-mcp-server convert html-to-docx document.html document.docx

CLI Options

• --full-doc: Create full HTML document with CSS styling (for md-to-html)

• --title "Document Title": Set the document title

• --help, -h: Show help information

🖥️ Server Modes

stdio Mode (Default)

For MCP client integration:

npx conversion-mcp-server          # Default stdio mode

HTTP Mode

For web-based integrations and testing:

npx conversion-mcp-server http               # HTTP server on port 3000
npx conversion-mcp-server http --port 8080   # HTTP server on port 8080

💡 Usage Examples

Once integrated with Claude Desktop, you can:

"Convert this HTML to PDF: <h1>Hello World</h1><p>This is a test.</p>"

"Convert this HTML to DOCX: <h1>Hello World</h1><p>This is a test.</p>"

"Convert this Markdown to PDF and save it to ~/Documents/report.pdf:
# My Report
## Summary
This is a **sample** report."

"Convert this Markdown to DOCX and save it to ~/Documents/report.docx:
# My Report
## Summary
This is a **sample** report with *emphasis*."

"Convert the webpage https://example.com to PDF format"

"Convert the webpage https://example.com to DOCX format"

"Convert my markdown file at ~/Documents/notes.md to a PDF"

"Convert my markdown file at ~/Documents/notes.md to a DOCX"

📁 Project Structure

conversion-mcp-server/
├── src/
│   ├── converters/
│   │   ├── htmlToPdf.ts          # HTML to PDF conversion
│   │   ├── htmlToDocx.ts         # HTML to DOCX conversion
│   │   ├── markdownToHtml.ts     # Markdown to HTML conversion
│   │   ├── markdownToPdf.ts      # Markdown to PDF conversion
│   │   ├── markdownToDocx.ts     # Markdown to DOCX conversion
│   │   └── index.ts              # Converter exports
│   ├── index.ts                  # Main MCP server
│   └── http-server.ts            # HTTP server mode
├── dist/                         # Compiled JavaScript
├── test/                         # Test files and examples
├── package.json
├── tsconfig.json
└── README.md

🛠️ Development Scripts

• npm run build - Build for production

• npm run dev - Start development server

• npm run dev:http - Start HTTP development server

• npm run lint - Run ESLint

• npm run lint:fix - Fix ESLint issues

• npm run clean - Clean build directory

• npm run watch - Watch mode for development

⚙️ How It Works

HTML to PDF

1. HTML Processing: Validates and processes HTML content

2. Browser Launch: Launches headless Puppeteer browser

3. Content Rendering: Loads HTML content with network idle wait

4. PDF Generation: Generates PDF with specified options

5. File Output: Saves PDF to specified location

HTML to DOCX

1. HTML Processing: Validates and processes HTML content

2. Metadata Integration: Adds document properties (title, author, etc.)

3. DOCX Generation: Uses html-docx-js library for conversion

4. Buffer Handling: Handles Blob/Buffer conversion for Node.js

5. File Output: Saves DOCX to specified location

Markdown to HTML

1. Markdown Parsing: Uses Marked library to parse Markdown

2. HTML Generation: Converts to clean HTML with GFM support

3. Sanitization: Optional HTML sanitization for security

4. Styling: Optional full document generation with CSS

Markdown to PDF

1. Two-Step Process: Markdown → HTML → PDF

2. Integrated Styling: Automatic CSS styling for readability

3. Document Structure: Full HTML document generation

4. PDF Optimization: Optimized for print layouts

Markdown to DOCX

1. Three-Step Process: Markdown → HTML → DOCX

2. Style Integration: Automatic CSS styling and document formatting

3. Document Structure: Full HTML document with metadata

4. DOCX Optimization: Optimized for Microsoft Word compatibility

🔒 Security Features

• HTML Sanitization: Removes dangerous scripts and content

• Input Validation: Comprehensive input validation using Zod

• File System Safety: Path validation and directory checks

• Browser Isolation: Each conversion runs in isolated browser instance

• Error Handling: Graceful error handling with detailed messages

🎨 Customization Options

PDF Options

• Formats: A4, A3, A2, A1, A0, Legal, Letter, Tabloid

• Orientation: Portrait or Landscape

• Margins: Custom margins in cm, mm, or inches

• Scale: 0.1x to 2x webpage rendering scale

• Background: Option to include/exclude background graphics

• Headers/Footers: Custom header and footer templates

DOCX Options

• Orientation: Portrait or Landscape

• Margins: Custom margins in twips (1440 twips = 1 inch)

  • Page margins: top, right, bottom, left

  • Additional: header, footer, gutter margins

• Document Properties: Title, subject, creator, keywords, description

• Content Processing: HTML sanitization and styling options

Markdown Options

• GitHub Flavored Markdown: Full GFM support

• Line Breaks: Convert single line breaks to <br>

• Sanitization: Remove potentially dangerous HTML

• Custom CSS: Add custom styles to generated documents

🚨 Troubleshooting

Common Issues

1. "Puppeteer browser not found"

   • Run npm install puppeteer to download Chrome

   • Or install system Chrome/Chromium

2. "Directory does not exist" errors

   • Ensure output directories exist before conversion

   • Use absolute paths for reliability

3. Large file failures

   • Increase Node.js memory limit: --max-old-space-size=4096

   • Use streaming for very large documents

4. Claude Desktop not recognizing server

   • Check config file path and JSON syntax

   • Ensure correct command and args in configuration

   • Restart Claude Desktop after config changes

Performance Tips

• Use headless mode for better performance (default)

• Set appropriate timeouts for large documents

• Consider batch processing for multiple files

• Use sanitization only when necessary

🌍 Supported Formats

Input Formats

• HTML: Full HTML documents or fragments

• Markdown: Standard Markdown and GitHub Flavored Markdown

• URLs: Any accessible web page

• Files: .html, .htm, .md, .markdown files

Output Formats

• PDF: High-quality PDF documents

• DOCX: Microsoft Word compatible documents

• HTML: Clean, styled HTML documents

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests: npm run lint && npm run build

5. Submit a Pull Request

🔗 Resources

• Model Context Protocol Documentation

• Claude Desktop

• Puppeteer Documentation

• Marked Documentation

Ready to convert documents? 🚀

Configure Claude Desktop and start converting HTML/Markdown to PDF and DOCX!