# HTML Email Playbook

> HTML Email Playbook is an open-source MCP server for communication. Gives AI clients tested rules and components for HTML email that renders in Outlook. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Web, API
- **Website:** https://docs.osamahassouna.com/email-playbook/
- **Repository:** https://github.com/osamahassouna/docs-hub/tree/HEAD/mcp
- **MCP Registry name:** io.github.OsamaHassouna/email-playbook-mcp
- **Categories:** communication, developer tools, design and media
- **Listing updated:** 2026-11-14

## About

Language models tend to reach for flex and grid, hard-code table widths and skip the VML fallback that Outlook buttons need. This server swaps that guesswork for lookup tools: the model pulls the playbook's rules and component patterns, then builds the email from them. The README says it is a knowledge server only, with no inbox access and no network calls of its own, and has one dependency (the official MCP SDK) and no postinstall scripts.

A typical session starts with list_categories, then get_playbook_rules (a checklist of roughly 16 KB), get_rule for a specific page such as responsive compatibility, and list_components with get_component for items like buttons. The playbook behind it covers table layout, inline styles, Outlook MSO conditional comments, RTL, dark mode, preheaders and the 102 KB Gmail clip limit, all written by one UI engineer, Osama Hassouna, and tested against Outlook on Windows, Gmail and Apple Mail.

It installs from npm, also ships a CLI for scripting, and has a hosted endpoint. A local copy older than 90 days prints an update note, which an environment variable turns off. A separate web Playground turns a pasted screenshot into email HTML.

## Features

- **Rule lookup tools:** The model fetches exact email-rendering rules by category or page instead of guessing.
- **Component patterns:** Get patterns such as bulletproof buttons, including whether VML is required.
- **No mailbox access:** The tools return playbook content only and never read or send mail.
- **CLI included:** A second binary queries the same content for scripts.
- **Staleness notice:** Bundled rules older than 90 days trigger a note to update.
- **Hosted or local:** Run over stdio from npm or use the hosted Streamable HTTP endpoint.

## Good for

- Turn a design into Outlook-safe table-based HTML
- Make an AI client add the VML fallback for buttons
- Check an email against Gmail's 102 KB clip limit
- Add dark mode and preheader text correctly
- Query individual email components from a script

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http email-playbook-mcp https://docs.osamahassouna.com/api/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://docs.osamahassouna.com/api/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "email-playbook-mcp": {
      "url": "https://docs.osamahassouna.com/api/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "email-playbook-mcp": {
      "type": "http",
      "url": "https://docs.osamahassouna.com/api/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "email-playbook-mcp": {
      "serverUrl": "https://docs.osamahassouna.com/api/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "email-playbook-mcp": {
      "type": "http",
      "url": "https://docs.osamahassouna.com/api/mcp"
    }
  }
}
```

## Tools

- `list_categories`: Lists the playbook's page slugs to orient the model.
- `get_playbook_rules`: Returns every page's rules, for example as a checklist.
- `get_rule`: Returns the rules for one page by slug.
- `list_components`: Lists the available component patterns.
- `get_component`: Returns the pattern for one component, such as buttons.

## FAQ

### Does it touch my email account?

No. The README says it never reads or sends mail and asks for no Gmail, Outlook or SMTP credentials.

### How do I install it?

Run npx -y email-playbook-mcp@latest or install it globally with npm; the README advises not pinning a version.

### Which clients work?

Claude Desktop, Cursor, Cline, Continue, Windsurf and other MCP clients that start a command.

### Is there a hosted version?

Yes, at https://docs.osamahassouna.com/api/mcp.

### What if my local rules are old?

After 90 days the server adds an update note; set EMAIL_PLAYBOOK_NO_STALE_NOTICE=1 to turn it off.

### Is HTML Email Playbook free?

Yes. HTML Email Playbook is open source, so you can use and self-host it for free.

### How do I add HTML Email Playbook to Claude Code?

Run this command in your terminal: claude mcp add --transport http email-playbook-mcp https://docs.osamahassouna.com/api/mcp

### What are the best alternatives to HTML Email Playbook?

The closest alternatives to HTML Email Playbook are REA, HyperFrames by HeyGen, Codebase Memory, GitHub and Serena MCP: the IDE for your agent.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/html-email-playbook
