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:

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.