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

🔧 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!