conversion-mcp-server

yokowasis/conversion-mcp-server

3.1

If you are the rightful owner of conversion-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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.

Tools
5
Resources
0
Prompts
0

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

Ready to convert documents? 🚀

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