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 pathfilePath(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 configurationoutputPath(optional): Save compiled HTML to file path
2. validate_mjml
Validate MJML syntax and structure.
Parameters:
input(required): MJML content or file pathfilePath(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 replacecustomColors(optional): Custom color schemecustomFonts(optional): Custom fontsoutputPath(optional): Save template to file path
4. get_component_info
Get MJML component reference and documentation.
Parameters:
component(optional): Specific component namecategory(optional): Component category - "all", "standard", "advanced", "structural" (default: "all")
Installation
- Clone or create the project directory
- 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 namecompany_logo: URL to company logouser_name: Recipient's namenewsletter_date: Date for newslettermain_title: Main title/headingmain_subtitle: Main subtitlefeatured_image: Featured image URLfeatured_title: Featured article titlefeatured_content: Featured article contentfeatured_link: Featured article linkupdate1_title,update1_content: First updateupdate2_title,update2_content: Second updatediscount_percentage: Discount percentage for promotionstime_remaining: Time remaining for promotionsproduct_name,product_image,product_description: Product detailsoriginal_price,sale_price: Pricing informationshop_url: Shopping URLdashboard_url: Dashboard URLsupport_email: Support email addressunsubscribe_url: Unsubscribe linkwebsite_url: Website URLfacebook_url,twitter_url,instagram_url: Social media URLscurrent_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 informationWARN: WarningsERROR: Error messagesDEBUG: 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 implementationmjml: MJML compiler and validatorzod: Schema validationfs-extra: Enhanced file system operations
License
MIT License
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
Support
For issues and questions, please open an issue in the project repository.