JSPM

conversion-mcp-server

1.3.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 10
  • Score
    100M100P100Q39248F
  • License MIT

MCP Server for converting HTML/Markdown to PDF and other formats using Puppeteer and Marked

Package Exports

  • conversion-mcp-server
  • conversion-mcp-server/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (conversion-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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!