MJML MCP Server

A comprehensive Model Context Protocol (MCP) server for MJML email template generation, compilation, and validation. This server provides powerful tools for creating professional email templates using the MJML markup language.

Features

• MJML Compilation: Compile MJML to responsive HTML with advanced options

• Template Generation: Pre-built templates for common email types

• Validation: Validate MJML syntax and structure with configurable levels

• Component Reference: Get documentation and examples for MJML components

• File Support: Work with both MJML strings and files

• Robust Error Handling: Comprehensive error reporting and logging

Tools

1. compile_mjml

Compile MJML content to responsive HTML email.

Parameters:

• input (required): MJML content or file path

• filePath (optional): Treat input as file path (default: false)

• beautify (optional): Beautify output HTML (default: true)

• minify (optional): Minify output HTML (default: false)

• validationLevel (optional): Validation level - "skip", "soft", "strict" (default: "soft")

• keepComments (optional): Keep comments in output (default: false)

• fonts (optional): Custom fonts configuration

• outputPath (optional): Save compiled HTML to file path

2. validate_mjml

Validate MJML syntax and structure.

Parameters:

• input (required): MJML content or file path

• filePath (optional): Treat input as file path (default: false)

• validationLevel (optional): Validation level - "skip", "soft", "strict" (default: "strict")

3. generate_template

Generate pre-built email templates.

Parameters:

• template (required): Template type - "newsletter", "welcome", "promotional", "transactional", "password-reset", "verification", "announcement", "invitation"

• variables (optional): Template variables to replace

• customColors (optional): Custom color scheme

• customFonts (optional): Custom fonts

• outputPath (optional): Save template to file path

4. get_component_info

Get MJML component reference and documentation.

Parameters:

• component (optional): Specific component name

• category (optional): Component category - "all", "standard", "advanced", "structural" (default: "all")

Installation

1. Clone or create the project directory

2. Install dependencies:

Usage

Start the Server

Development Mode

Running Tests

Template Variables

When generating templates, you can use these variables:

• company_name: Your company name

• company_logo: URL to company logo

• user_name: Recipient's name

• newsletter_date: Date for newsletter

• main_title: Main title/heading

• main_subtitle: Main subtitle

• featured_image: Featured image URL

• featured_title: Featured article title

• featured_content: Featured article content

• featured_link: Featured article link

• update1_title, update1_content: First update

• update2_title, update2_content: Second update

• discount_percentage: Discount percentage for promotions

• time_remaining: Time remaining for promotions

• product_name, product_image, product_description: Product details

• original_price, sale_price: Pricing information

• shop_url: Shopping URL

• dashboard_url: Dashboard URL

• support_email: Support email address

• unsubscribe_url: Unsubscribe link

• website_url: Website URL

• facebook_url, twitter_url, instagram_url: Social media URLs

• current_year: Current year (automatically filled)

Example Usage

Compile MJML from String

Generate Welcome Template

Validate MJML File

Get Component Information

Error Handling

The server provides comprehensive error handling with detailed error messages:

• File access errors

• MJML syntax errors

• Validation failures

• Configuration issues

Logging

The server includes structured logging with different levels:

• INFO: General information

• WARN: Warnings

• ERROR: Error messages

• DEBUG: Debug information (enable with DEBUG environment variable)

Enable debug logging:

Configuration

The server supports various MJML options:

• Custom fonts configuration

• Validation levels

• Output formatting options

• File input/output handling

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for server implementation

• mjml: MJML compiler and validator

• zod: Schema validation

• fs-extra: Enhanced file system operations

License

MIT License

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

Support

For issues and questions, please open an issue in the project repository.