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

Related MCP server: Email Send/Receive MCP Server

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:

npm install

Usage

Start the Server

npm start

Development Mode

npm run dev

Running Tests

npm test

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

{
  "name": "compile_mjml",
  "arguments": {
    "input": "<mjml><mj-body><mj-section><mj-column><mj-text>Hello World!</mj-text></mj-column></mj-section></mj-body></mjml>",
    "beautify": true,
    "validationLevel": "soft"
  }
}

Generate Welcome Template

{
  "name": "generate_template",
  "arguments": {
    "template": "welcome",
    "variables": {
      "company_name": "Acme Corp",
      "user_name": "John Doe",
      "support_email": "support@acme.com"
    },
    "customColors": {
      "primary": "#007bff",
      "success": "#28a745"
    },
    "outputPath": "./welcome-email.mjml"
  }
}

Validate MJML File

{
  "name": "validate_mjml",
  "arguments": {
    "input": "./templates/newsletter.mjml",
    "filePath": true,
    "validationLevel": "strict"
  }
}

Get Component Information

{
  "name": "get_component_info",
  "arguments": {
    "component": "mj-button"
  }
}

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:

DEBUG=1 npm start

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.