email-design-mcp

An open-source MCP server that enables AI assistants to design and generate professional, responsive email templates.

Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP-compatible client.

Features

• Generate emails from natural language - Describe what you want, get production-ready MJML + HTML
• Brand memory - Save brand colors, fonts, and tone once, use across all emails
• Expert design built-in - Professional spacing, typography, color usage, and CTA patterns enforced automatically
• Iterative refinement - Say "make the headline bigger" or "remove the testimonials section" in plain English
• Layout variety - 12 layout variants across 4 email types prevent repetitive designs
• Live preview - Local preview server with hot reload at http://localhost:3947
• Validation - Checks size limits, dark mode, accessibility, links, and more
• Export - Get HTML, MJML, or both for any generated email
• Guided workflows - MCP prompts walk you through creating welcome, newsletter, promotional, and transactional emails
• No API keys needed - Uses the host AI model (Claude, GPT, etc.) for generation

Quick Start

Install

npm install -g email-design-mcp

Connect to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "email-design": {
      "command": "email-design-mcp"
    }
  }
}

Connect to Cursor / VS Code

Add to .cursor/mcp.json or VS Code MCP settings:

{
  "mcpServers": {
    "email-design": {
      "command": "npx",
      "args": ["email-design-mcp"]
    }
  }
}

Usage

1. Set up your brand (optional but recommended)

Option A — Auto-extract from website:

"Set up a brand from https://acme.com"

The server fetches the site and extracts colors, fonts, logo, and name automatically.

Option B — Manual setup:

"Set up a brand called Acme with primary color #FF6B35, secondary #1A1A2E, casual tone, targeting young professionals"

You can also combine both — provide a URL for auto-extraction and override specific values manually.

2. Generate an email

"Create a welcome email for new subscribers"

The server composes an expert prompt stack with design rules, brand context, and layout instructions. The AI generates MJML, which is compiled to responsive HTML.

3. Refine

"Make the headline bigger and change the button to say 'Start Free Trial'"

Refinements target specific sections without regenerating the whole email. Version history lets you undo changes.

4. Export

"Export the email as HTML"

Get the final HTML or MJML ready to paste into your ESP.

Tools

Tool	Description
setup_brand	Save a brand profile (colors, fonts, tone)
generate_email	Generate an email from a natural language prompt
refine_email	Iterate on a generated email with feedback
compile_mjml	Compile raw MJML to HTML
validate_email	Check email for best practices
export_email	Export as HTML, MJML, or both
screenshot_to_email	Convert a design description to a branded email

Guided Workflows (MCP Prompts)

These prompts walk you through creating specific email types with smart defaults:

Prompt	Description
welcome-email	Welcome email for new subscribers
newsletter	Newsletter with featured content
promotional	Sale/launch email with urgency
transactional	Receipt, confirmation, or shipping notification

Templates

4 bundled MJML templates with placeholder variables:

• Welcome - Hero image + intro text + CTA
• Newsletter - Featured article + content grid + footer
• Promotional - Hero offer + product showcase + urgency
• Transactional - Order confirmation with itemized details

Validation Checks

Check	What it verifies
Email size	Under Gmail's 102KB clipping threshold
Dark mode	color-scheme: light dark declaration
Alt text	All images have meaningful alt attributes
Links	All <a> tags have href attributes
Unsubscribe	Footer contains unsubscribe link
Text ratio	Sufficient text relative to images
Viewport	Mobile viewport meta tag
Preheader	Hidden preview text for inbox
Title	HTML title tag present
Inline styles	Styles inlined for email client compatibility

Storage

Data is stored at ~/.email-design-mcp/:

~/.email-design-mcp/
  brands/           # Brand profiles (JSON)
  history/          # Generated email history (JSON)
  config.json       # Optional config (history retention, preview port)

History is automatically cleaned up after 30 days (configurable in config.json).

Development

git clone https://github.com/harikrishna8121999/email-design-mcp.git
cd email-design-mcp
npm install
npm run dev        # Watch mode
npm test           # Run tests
npm run typecheck  # Type check
npm run build      # Compile TypeScript

Architecture

See ARCHITECTURE.md for the full design document.

Stack: TypeScript, Node.js, MJML, Zod, MCP SDK

Key design decisions:

• No external AI API calls - the host model does generation
• Prompt engineering layer (expert system prompts + design rules + layout variants) is the core differentiator
• MJML for email rendering ensures Outlook/Gmail/mobile compatibility
• Local JSON storage keeps it simple with no database dependency

License

MIT