# Email MCP Server

**Universal email integration for AI assistants.** Works with Gmail, Outlook, Yahoo, Zoho, iCloud, AOL, and any IMAP email provider.

Read, send, reply, draft, manage, clean up, run cold email campaigns, auto-triage, and track follow-ups — all through the Model Context Protocol.

Compatible with **Claude Desktop**, **Cursor**, **Hermes Agent**, **Windsurf**, and any MCP client.

---

## Why This Exists

Every email MCP out there only works with Gmail via Google Cloud OAuth. This one:

- **Works with ANY email provider** — Gmail, Outlook, Yahoo, Zoho, iCloud, AOL, custom domains
- **No Google Cloud project needed** — uses IMAP + App Passwords (free, 30 seconds)
- **18 tools** — full email management + AI-powered automation
- **Zero data leaves your machine** — everything runs locally

---

## Supported Providers (Auto-Detected)

| Provider | IMAP | SMTP |
|----------|------|------|
| Gmail / Google Workspace | imap.gmail.com:993 | smtp.gmail.com:465 |
| Outlook / Hotmail / Live | outlook.office365.com:993 | smtp.office365.com:587 |
| Yahoo Mail | imap.mail.yahoo.com:993 | smtp.mail.yahoo.com:465 |
| Zoho Mail (.com, .in, .eu, .com.au, .jp) | imap.zoho.com:993 | smtp.zoho.com:465 |
| iCloud / Me.com | imap.mail.me.com:993 | smtp.mail.me.com:587 |
| AOL Mail | imap.aol.com:993 | smtp.aol.com:465 |
| **Any custom IMAP** | Set `IMAP_HOST` env var | Set `SMTP_HOST` env var |

Just enter your email — the server auto-detects the provider.

---

## 18 Tools

### Read (5)
| Tool | Description |
|------|-------------|
| `email_search` | Search emails with query syntax |
| `email_read` | Read full email by ID |
| `email_read_thread` | Read entire conversation |
| `email_inbox` | Quick inbox view (unread filter) |
| `email_profile` | Account info |

### Send (5)
| Tool | Description |
|------|-------------|
| `email_send` | Send email (HTML, CC, BCC, threading) |
| `email_reply` | Reply to email (auto-sets headers) |
| `email_draft` | Create draft |
| `email_send_draft` | Send existing draft |
| `email_list_drafts` | List all drafts |

### Manage (8)
| Tool | Description |
|------|-------------|
| `email_labels` | List all folders/labels |
| `email_create_label` | Create new folder |
| `email_archive` | Archive messages |
| `email_trash` | Move to trash |
| `email_delete` | Permanent delete |
| `email_mark_read` / `email_mark_unread` | Toggle read status |
| `email_star` / `email_unstar` | Toggle star/flag |
| `email_add_label` / `email_remove_label` | Move between folders |

### Automation (7) — The Premium Features
| Tool | Description |
|------|-------------|
| `email_digest` | Morning summary grouped by sender |
| `email_suggest_reply` | Prepare AI reply context |
| `email_triage` | Classify unread by priority |
| `email_cleanup` | Archive old/newsletter/social (dry-run) |
| `email_cold_campaign` | Personalized bulk emails with placeholders |
| `email_follow_up` | Find sent emails with no reply |
| `email_contacts` | Extract contacts from email history |

---

## Quick Start

### 1. Generate an App Password

**Gmail:**
1. Go to https://myaccount.google.com/apppasswords
2. Select app → Generate → Copy the 16-char password

**Outlook/Hotmail:**
1. Go to https://account.live.com/proofs/AppPassword
2. Create new app password → Copy

**Yahoo:**
1. Go to https://login.yahoo.com/account/security
2. Generate app password for "Mail"

**Zoho:**
1. Go to https://accounts.zoho.com/home#security/app-passwords
2. Generate new app password → Copy

### 2. Install & Run

```bash
cd email-mcp-server
npm install
npm run build

# Set credentials
export EMAIL_ADDRESS="you@example.com"
export EMAIL_PASSWORD="your-app-password"

# Run
node build/index.js
```

### 3. Connect to Your AI

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "email": {
      "command": "node",
      "args": ["C:/path/to/email-mcp-server/build/index.js"],
      "env": {
        "EMAIL_ADDRESS": "you@example.com",
        "EMAIL_PASSWORD": "your-app-password"
      }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`): Same structure as above.

**Hermes Agent:**
```bash
hermes mcp add email --command node --args C:/path/to/email-mcp-server/build/index.js
```

---

## Usage Examples

> "Check my inbox and summarize the important emails"
> "Read the email from john@company.com and draft a reply"
> "Clean up my inbox — archive all newsletters older than 7 days"
> "Send cold emails to these 5 prospects about web development"
> "Show me emails I sent that haven't gotten a reply"
> "Triage my unread emails by priority"

---

## Cold Email Campaign

```json
{
  "recipients": [
    { "email": "john@acme.com", "name": "John", "company": "Acme Corp" },
    { "email": "sarah@startup.io", "name": "Sarah", "company": "StartupIO" }
  ],
  "subject_template": "Quick question about {{company}}'s tech stack",
  "body_template": "<p>Hi {{name}},</p><p>I noticed {{company}} is growing fast...</p>",
  "create_drafts": true
}
```

Always use `create_drafts: true` first to review before sending.

---

## Custom IMAP/SMTP

For providers not in the auto-detect list:

```bash
export IMAP_HOST="mail.yourprovider.com"
export IMAP_PORT="993"
export SMTP_HOST="smtp.yourprovider.com"
export SMTP_PORT="465"
```

---

## Security

- Credentials in environment variables only (never written to disk)
- All processing local — no external API calls
- App Passwords revocable anytime from provider settings

---

## License

MIT — Use freely, modify, sell as part of your services.