@emailens/mcp

@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:

• Validates inputs with Zod schemas
• Calls engine functions (transformForAllClients, analyzeEmail, generateCompatibilityScore, simulateDarkMode, generateFixPrompt, estimateAiFixTokens)
• 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