@emailens/mcp

MCP (Model Context Protocol) server for email compatibility analysis. Enables Claude and other MCP-compatible AI assistants to preview, analyze, and score HTML emails across 12 email clients.

Built on top of @emailens/engine.

Install

npm install -g @emailens/mcp
# or
bunx @emailens/mcp

Usage with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "emailens": {
      "command": "npx",
      "args": ["-y", "@emailens/mcp"]
    }
  }
}

Or if using Bun:

{
  "mcpServers": {
    "emailens": {
      "command": "bunx",
      "args": ["@emailens/mcp"]
    }
  }
}

Usage with Claude Code

Add to your Claude Code settings:

claude mcp add emailens -- npx -y @emailens/mcp

Tools

The server exposes four tools:

preview_email

Full email compatibility preview — transforms HTML per client, analyzes CSS, generates scores, and simulates dark mode.

Parameters:

Name	Type	Required	Description
html	string	Yes	The email HTML source code
clients	string[]	No	Filter to specific client IDs (e.g. ["gmail_web", "outlook_windows"]). Omit for all 12 clients.
format	enum	No	Input format: "html" (default), "jsx" (React Email), "mjml", or "maizzle". Controls which framework-specific fix snippets appear.

Returns: JSON with overallScore (0–100), compatibilityScores (per-client), cssWarnings (with fix snippets), clientCount, and darkModeWarnings.

Example prompt:

Analyze this email HTML and tell me what will break in Gmail and Outlook:

<div style="display: flex; gap: 16px; border-radius: 8px;">...</div>

analyze_email

Quick CSS compatibility analysis — returns warnings and per-client scores without full transforms. Faster than preview_email when you only need the compatibility report.

Parameters:

Name	Type	Required	Description
html	string	Yes	The email HTML source code
format	enum	No	Input format: "html", "jsx", "mjml", or "maizzle"

Returns: JSON with overallScore, scores (per-client), warningCount, and warnings (with severity, message, and fix).

Example prompt:

What's the compatibility score for this React Email template?

fix_email

Generate a structured fix prompt for email compatibility issues. Analyzes the HTML, classifies each warning as CSS-only or structural (requires HTML restructuring), estimates token usage, and returns a markdown prompt the AI assistant can apply directly. Use after preview_email or analyze_email to fix the issues found.

Parameters:

Name	Type	Required	Description
html	string	Yes	The email HTML source code to fix
format	enum	No	Input format: "html" (default), "jsx", "mjml", or "maizzle". Controls the fix syntax.
scope	enum	No	"all" (default) or "current" (requires selectedClientId)
selectedClientId	string	No	Client ID to scope fixes to (e.g. "outlook-windows"). Only used when scope is "current".

Returns: JSON with totalWarnings, structuralWarnings, cssWarnings, tokenEstimate, and the full fix prompt as markdown.

Example prompt:

Fix this email HTML so it works in Outlook Windows — it uses flexbox and word-break which aren't supported.

list_clients

Lists all 12 supported email client IDs, display names, categories, rendering engines, and dark mode support. Useful for discovering valid client IDs to pass to preview_email or fix_email.

Parameters: None

Returns: JSON array of { id, name, category, engine, darkModeSupport } objects.

Example prompt:

What email clients does Emailens support?

Supported Email Clients

Client	ID	Dark Mode
Gmail	gmail-web	Yes
Gmail Android	gmail-android	Yes
Gmail iOS	gmail-ios	Yes
Outlook 365	outlook-web	Yes
Outlook Windows	outlook-windows	No
Apple Mail	apple-mail-macos	Yes
Apple Mail iOS	apple-mail-ios	Yes
Yahoo Mail	yahoo-mail	Yes
Samsung Mail	samsung-mail	Yes
Thunderbird	thunderbird	No
HEY Mail	hey-mail	Yes
Superhuman	superhuman	Yes

Framework-Aware Fixes

When you specify a format, the fix snippets in warnings are tailored to your framework:

• jsx — References React Email components (Row, Column, Font, Container from @react-email/components)
• mjml — References MJML elements (mj-section, mj-column, mj-font, mj-style)
• maizzle — References Tailwind CSS classes and Maizzle config (googleFonts, MSO conditionals)
• html (default) — Generic HTML with VML fallbacks for Outlook

Fix Types (v0.2.0)

Every warning now includes a fixType field:

• css — Can be fixed with CSS swaps or fallbacks
• structural — Requires HTML restructuring (tables, VML, MSO conditionals). CSS-only changes will NOT work.

The fix_email tool uses this classification to generate targeted fix instructions that the AI assistant can apply directly.

How It Works

The MCP server is a thin wrapper around @emailens/engine. For each tool call, it:

1. Validates inputs with Zod schemas
2. Calls engine functions (transformForAllClients, analyzeEmail, generateCompatibilityScore, simulateDarkMode, generateFixPrompt, estimateAiFixTokens)
3. Formats and returns JSON results via stdio transport

The engine uses Cheerio for HTML manipulation and css-tree for CSS parsing. No external API calls — all analysis and fix prompt generation runs locally. The fix_email tool generates a prompt for the AI assistant to apply — it does not call any AI API itself.

Development

# Install dependencies
bun install

# Build
bun run build

# Run locally
bun run src/index.ts

# Type check
bun run typecheck

License

MIT