An MCP (Model Context Protocol) server providing comprehensive email capabilities via IMAP and SMTP. Enables AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts. Exposes 47 tools, 7 prompts, and 6 resources over the MCP protocol with OAuth2 support (experimental), email scheduling, calendar extraction, analytics, provider-aware label management, real-
Add this skill
npx mdskills install codefuturist/email-mcpComprehensive multi-provider email MCP with 24 tools, OAuth flows, and excellent setup documentation
1# Email MCP Server23[](https://github.com/RichardLitt/standard-readme)4[](LICENSE)5[](https://www.npmjs.com/package/@codefuturist/email-mcp)6[](https://www.npmjs.com/package/@codefuturist/email-mcp)7[](https://github.com/codefuturist/email-mcp/actions/workflows/ci.yml)89An MCP (Model Context Protocol) server providing comprehensive email capabilities via IMAP and SMTP.1011Enables AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts. Exposes 47 tools, 7 prompts, and 6 resources over the MCP protocol with OAuth2 support _(experimental)_, email scheduling, calendar extraction, analytics, provider-aware label management, real-time IMAP IDLE watcher with AI-powered triage, customizable presets and static rules, and a guided setup wizard.1213## Highlights1415| Feature | email-mcp | Typical MCP email |16|---------|:---------:|:-----------------:|17| Multi-account | ✅ | ❌ |18| Send / reply / forward | ✅ | ✅ |19| Drafts & templates | ✅ | ❌ |20| Labels & bulk ops | ✅ provider-aware | ❌ |21| Schedule future emails | ✅ | ❌ |22| Real-time IMAP IDLE watcher | ✅ | ❌ |23| AI triage with presets | ✅ | ❌ |24| Desktop & webhook alerts | ✅ | ❌ |25| Calendar (ICS) extraction | ✅ | ❌ |26| Email analytics | ✅ | ❌ |27| OAuth2 (Gmail / M365) | ✅ _experimental_ | ❌ |28| Guided setup wizard | ✅ auto-detect | ❌ |2930## Table of Contents3132- [Highlights](#highlights)33- [Security](#security)34- [Background](#background)35- [Install](#install)36- [Usage](#usage)37- [API](#api)38- [Maintainers](#maintainers)39- [Contributing](#contributing)40- [License](#license)4142## Security4344- All connections use TLS/STARTTLS encryption45- Passwords are never logged; audit trail records operations without credentials46- Token-bucket rate limiter prevents abuse (configurable per account)47- OAuth2 XOAUTH2 authentication for Gmail and Microsoft 365 _(experimental)_48- Attachment downloads capped at 5 MB with base64 encoding4950## Background5152Most MCP email implementations provide only basic read/send. This server aims to be a full-featured email client for AI assistants, covering the entire lifecycle: reading, composing, managing, scheduling, and analyzing email — all from a single MCP server.5354Key design decisions:5556- **XDG-compliant config** — TOML at `~/.config/email-mcp/config.toml`57- **Multi-account** — Operate across multiple IMAP/SMTP accounts simultaneously58- **Layered services** — Business logic is decoupled from MCP wiring for testability59- **Provider auto-detection** — Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX6061## Install6263Requires Node.js ≥ 22.6465```bash66# Run directly (no install needed)67npx @codefuturist/email-mcp setup68# or69pnpm dlx @codefuturist/email-mcp setup7071# Or install globally72npm install -g @codefuturist/email-mcp73# or74pnpm add -g @codefuturist/email-mcp75```7677### Docker7879No Node.js required — just Docker.8081```bash82# Latest stable release83docker pull ghcr.io/codefuturist/email-mcp:latest8485# Pin to an exact version (immutable)86docker pull ghcr.io/codefuturist/email-mcp:0.2.38788# Auto-update patches within a minor version89docker pull ghcr.io/codefuturist/email-mcp:0.29091# Track a major version (won't cross breaking-change boundary)92docker pull ghcr.io/codefuturist/email-mcp:09394# Pin to an exact git commit (immutable, CI traceability)95docker pull ghcr.io/codefuturist/email-mcp:sha-abc12349697# Or build from source98docker build -t ghcr.io/codefuturist/email-mcp .99```100101> **Tag convention:** Tags follow bare semver (no `v` prefix), matching Docker ecosystem standards (e.g. `node:24`, `nginx:1.25`). The `latest` tag is only updated on stable releases, never pre-releases.102103> **Note:** The server uses stdio transport. Config must be created on the host first104> (via `npx @codefuturist/email-mcp setup` or manually) and mounted into the container.105106## Usage107108### Setup109110```bash111# Add an email account interactively (recommended)112email-mcp account add113114# Or use the legacy alias115email-mcp setup116117# Or create a template config manually118email-mcp config init119```120121The setup wizard auto-detects server settings, tests connections, saves config, and outputs the MCP client config snippet.122123### Test Connections124125```bash126email-mcp test # all accounts127email-mcp test personal # specific account128```129130### Configure Your MCP Client131132**Recommended — use the guided installer** (auto-detects Claude Desktop, VS Code, Cursor, Windsurf):133134```bash135email-mcp install136```137138Or add manually using the snippets below.139140<details>141<summary><strong>Claude Desktop</strong></summary>142143Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):144145```json146{147 "mcpServers": {148 "email": {149 "command": "npx",150 "args": ["-y", "@codefuturist/email-mcp", "stdio"]151 }152 }153}154```155</details>156157<details>158<summary><strong>VS Code (GitHub Copilot)</strong></summary>159160**Option 1 — Extensions gallery (easiest):**1611. Open the Extensions view (<kbd>⇧⌘X</kbd> / <kbd>Ctrl+Shift+X</kbd>)1622. Search `@mcp email-mcp`1633. Click **Install** (user-wide) or right-click → **Install in Workspace**164165**Option 2 — Workspace config** (`.vscode/mcp.json`, committed to source control):166167```json168{169 "servers": {170 "email": {171 "type": "stdio",172 "command": "npx",173 "args": ["-y", "@codefuturist/email-mcp", "stdio"]174 }175 }176}177```178179**Option 3 — User config** (`settings.json`, applies to all workspaces):180181Open the Command Palette → **Preferences: Open User Settings (JSON)** and add:182183```json184{185 "mcp": {186 "servers": {187 "email": {188 "type": "stdio",189 "command": "npx",190 "args": ["-y", "@codefuturist/email-mcp", "stdio"]191 }192 }193 }194}195```196</details>197198<details>199<summary><strong>Cursor</strong></summary>200201Edit `~/.cursor/mcp.json`:202203```json204{205 "mcpServers": {206 "email": {207 "command": "npx",208 "args": ["-y", "@codefuturist/email-mcp", "stdio"]209 }210 }211}212```213</details>214215<details>216<summary><strong>Windsurf</strong></summary>217218Edit `~/.codeium/windsurf/mcp_config.json`:219220```json221{222 "mcpServers": {223 "email": {224 "command": "npx",225 "args": ["-y", "@codefuturist/email-mcp", "stdio"]226 }227 }228}229```230</details>231232<details>233<summary><strong>Zed</strong></summary>234235Edit `~/.config/zed/settings.json`:236237```json238{239 "context_servers": {240 "email": {241 "command": {242 "path": "npx",243 "args": ["-y", "@codefuturist/email-mcp", "stdio"]244 }245 }246 }247}248```249</details>250251<details>252<summary><strong>Mistral Vibe</strong></summary>253254Add to `~/.vibe/config.toml`:255256```toml257[[mcp_servers]]258name = "email-mcp"259transport = "stdio"260command = "npx"261args = ["-y", "@codefuturist/email-mcp", "stdio"]262```263264To pass credentials directly instead of using a config file, use the `env` field:265266```toml267[[mcp_servers]]268name = "email-mcp"269transport = "stdio"270command = "npx"271args = ["-y", "@codefuturist/email-mcp", "stdio"]272env = { "EMAIL_ACCOUNTS" = "<your-accounts-json>" }273```274275MCP tools are exposed as `email-mcp_<tool_name>` (e.g. `email-mcp_list_emails`). Restart Vibe after editing the config.276277</details>278279<details>280<summary><strong>Docker (any MCP client)</strong></summary>281282Run the server in a container — mount your config directory read-only:283284```bash285docker run --rm -i \286 -v ~/.config/email-mcp:/home/node/.config/email-mcp:ro \287 ghcr.io/codefuturist/email-mcp288```289290For MCP client configuration (e.g. Claude Desktop):291292```json293{294 "mcpServers": {295 "email": {296 "command": "docker",297 "args": [298 "run", "--rm", "-i",299 "-v", "~/.config/email-mcp:/home/node/.config/email-mcp:ro",300 "ghcr.io/codefuturist/email-mcp"301 ]302 }303 }304}305```306</details>307308<details>309<summary><strong>Single-account via environment variables (no config file needed)</strong></summary>310311```json312{313 "mcpServers": {314 "email": {315 "command": "npx",316 "args": ["-y", "@codefuturist/email-mcp", "stdio"],317 "env": {318 "MCP_EMAIL_ADDRESS": "you@gmail.com",319 "MCP_EMAIL_PASSWORD": "your-app-password",320 "MCP_EMAIL_IMAP_HOST": "imap.gmail.com",321 "MCP_EMAIL_SMTP_HOST": "smtp.gmail.com"322 }323 }324 }325}326```327</details>328329### CLI Commands330331```332email-mcp [command]333334Commands:335 stdio Run as MCP server over stdio (default)336 account list List all configured accounts337 account add Add a new email account interactively338 account edit [name] Edit an existing account339 account delete [name] Remove an account340 setup Alias for 'account add'341 test Test connections for all or a specific account342 install Register email-mcp with MCP clients interactively343 install status Show registration status for detected clients344 install remove Unregister email-mcp from MCP clients345 config show Show config (passwords masked)346 config edit Edit global settings (rate limit, read-only)347 config path Print config file path348 config init Create template config349 scheduler check Process pending scheduled emails350 scheduler list Show all scheduled emails351 scheduler install Install OS-level scheduler (launchd/crontab)352 scheduler uninstall Remove OS-level scheduler353 scheduler status Show scheduler installation status354 help Show help355```356357### Configuration358359Located at `$XDG_CONFIG_HOME/email-mcp/config.toml` (default: `~/.config/email-mcp/config.toml`).360361```toml362[settings]363rate_limit = 10 # max emails per minute per account364365[[accounts]]366name = "personal"367email = "you@gmail.com"368full_name = "Your Name"369password = "your-app-password"370371[accounts.imap]372host = "imap.gmail.com"373port = 993374tls = true375376[accounts.smtp]377host = "smtp.gmail.com"378port = 465379tls = true380starttls = false381verify_ssl = true382383[accounts.smtp.pool]384enabled = true385max_connections = 1386max_messages = 100387```388389#### OAuth2 _(experimental)_390391> **Note:** OAuth2 support is experimental. Token refresh and provider-specific flows may require additional testing in your environment.392393```toml394[[accounts]]395name = "work"396email = "you@company.com"397full_name = "Your Name"398399[accounts.oauth2]400provider = "google" # or "microsoft"401client_id = "your-client-id"402client_secret = "your-client-secret"403refresh_token = "your-refresh-token"404405[accounts.imap]406host = "imap.gmail.com"407port = 993408tls = true409410[accounts.smtp]411host = "smtp.gmail.com"412port = 465413tls = true414415[accounts.smtp.pool]416enabled = true417max_connections = 1418max_messages = 100419```420421#### Environment Variables422423For single-account setups (overrides config file):424425| Variable | Default | Description |426|----------|---------|-------------|427| `MCP_EMAIL_ADDRESS` | *required* | Email address |428| `MCP_EMAIL_PASSWORD` | *required* | Password or app password |429| `MCP_EMAIL_IMAP_HOST` | *required* | IMAP server hostname |430| `MCP_EMAIL_SMTP_HOST` | *required* | SMTP server hostname |431| `MCP_EMAIL_ACCOUNT_NAME` | `default` | Account name |432| `MCP_EMAIL_FULL_NAME` | — | Display name |433| `MCP_EMAIL_USERNAME` | *email* | Login username |434| `MCP_EMAIL_IMAP_PORT` | `993` | IMAP port |435| `MCP_EMAIL_IMAP_TLS` | `true` | IMAP TLS |436| `MCP_EMAIL_SMTP_PORT` | `465` | SMTP port |437| `MCP_EMAIL_SMTP_TLS` | `true` | SMTP TLS |438| `MCP_EMAIL_SMTP_STARTTLS` | `false` | SMTP STARTTLS |439| `MCP_EMAIL_SMTP_VERIFY_SSL` | `true` | Verify SSL certificates |440| `MCP_EMAIL_SMTP_POOL_ENABLED` | `true` | Enable SMTP transport pooling |441| `MCP_EMAIL_SMTP_POOL_MAX_CONNECTIONS` | `1` | Max pooled SMTP connections |442| `MCP_EMAIL_SMTP_POOL_MAX_MESSAGES` | `100` | Max messages per pooled connection |443| `MCP_EMAIL_RATE_LIMIT` | `10` | Max sends per minute |444445### Email Scheduling446447The scheduler enables future email delivery with a layered architecture:4484491. **MCP auto-check** — Processes the queue on server startup and every 60 seconds while the MCP server is running4502. **CLI** — `email-mcp scheduler check` for manual or cron-based processing4513. **OS-level daemon** — `email-mcp scheduler install` sets up launchd (macOS) or crontab (Linux) to run every minute, independently of the MCP server452453> **Important — the daemon must be installed for reliable delivery.**454> Without it, scheduled emails only fire while an AI client is actively connected.455> Your machine also needs to be running at the scheduled time; if it's asleep or456> off, the daemon will process overdue emails on next wake/startup. Failed sends457> are retried up to **3 times** before being marked `failed`.458459#### Setting up the daemon460461```bash462# Install (macOS launchd / Linux crontab — runs every minute)463email-mcp scheduler install464465# Verify it's running466email-mcp scheduler status467468# View pending / sent / failed scheduled emails469email-mcp scheduler list470471# Trigger a manual check immediately472email-mcp scheduler check473474# Remove the daemon475email-mcp scheduler uninstall476```477478Scheduled emails are stored as JSON files in `~/.local/state/email-mcp/scheduled/` with status-based locking. Each entry tracks attempts (max 3) and the last error, so you can inspect failures with `scheduler list`.479480### Real-time Watcher & AI Hooks481482The IMAP IDLE watcher monitors configured mailboxes in real-time using persistent IDLE connections (separate from tool connections). When new emails arrive:4834841. **Static rules** — Pattern-match on from/to/subject → apply labels, flag, or mark read instantly (no AI)4852. **AI triage** — Remaining emails are analyzed via MCP sampling with a customizable preset prompt4863. **Notify mode** — Falls back to logging if AI triage is disabled487488Configure in `config.toml`:489490```toml491[settings.watcher]492enabled = true493folders = ["INBOX"]494idle_timeout = 1740 # 29 minutes (IMAP spec max is 30)495496[settings.hooks]497on_new_email = "triage" # "triage" | "notify" | "none"498preset = "inbox-zero" # "inbox-zero" | "gtd" | "priority-focus" | "notification-only" | "custom"499auto_label = true # apply AI-suggested labels500auto_flag = true # flag urgent emails501batch_delay = 5 # seconds to batch before triage502503# User context — appended to preset's AI prompt504custom_instructions = """505I'm a software engineer. Emails from @mycompany.com are always high priority.506Newsletters I read: TL;DR, Hacker Newsletter.507"""508509# Static rules — run BEFORE AI, skip AI if matched510[[settings.hooks.rules]]511name = "GitHub Notifications"512match = { from = "*@github.com" }513actions = { labels = ["Dev"], mark_read = true }514515[[settings.hooks.rules]]516name = "Newsletter Archive"517match = { from = "*@substack.com|*@buttondown.email" }518actions = { labels = ["Newsletter"] }519520[[settings.hooks.rules]]521name = "VIP Contacts"522match = { from = "ceo@company.com|cto@company.com" }523actions = { flag = true, labels = ["VIP"] }524```525526#### Presets527528| Preset | Focus | Suggested Labels |529|--------|-------|------------------|530| `inbox-zero` | Aggressive categorization + archiving | Newsletter, Notification, Updates, Finance, Social, Promo |531| `gtd` | Getting Things Done contexts | @Action, @Waiting, @Reference, @Someday, @Delegated |532| `priority-focus` | Simple priority classification (default) | _(none — just priority + flag)_ |533| `notification-only` | No AI triage, just log | _(none)_ |534| `custom` | User defines full system prompt | User-defined |535536#### Static Rules537538Static rules use glob-style patterns (`*@github.com`) with `|` as OR separator (`*@github.com|*@gitlab.com`). All conditions within a match are AND'd. First matching rule wins.539540Available actions: `labels` (string array), `flag` (boolean), `mark_read` (boolean), `alert` (boolean — forces desktop notification).541542#### Alerts543544Urgency-based multi-channel notification routing — grab attention for important emails even when you're not looking at the chat. All channels are **opt-in** and disabled by default.545546| Priority | Desktop | Sound | MCP Log Level | Webhook |547|----------|---------|-------|---------------|---------|548| `urgent` | ✅ Banner | 🔊 Alert | `alert` | ✅ |549| `high` | ✅ Banner | 🔇 Silent | `warning` | ✅ |550| `normal` | ❌ | ❌ | `info` | ❌ |551| `low` | ❌ | ❌ | `debug` | ❌ |552553```toml554[settings.hooks.alerts]555desktop = true # OS-level notifications (macOS/Linux/Windows)556sound = true # play sound for urgent emails557urgency_threshold = "high" # minimum priority to trigger desktop alert558webhook_url = "https://ntfy.sh/my-email-alerts" # optional: Slack, Discord, ntfy.sh, etc.559webhook_events = ["urgent", "high"]560```561562**Supported platforms:** macOS (Notification Center via `osascript`), Linux (`notify-send`), Windows (PowerShell toast). Zero npm dependencies — uses native OS commands.563564**Notification setup by platform:**565566<details>567<summary>macOS</summary>568569Desktop notifications use `osascript` (built-in). The terminal app running the MCP server needs notification permission:5705711. Open **System Settings → Notifications & Focus**5722. Find your terminal app (Terminal, iTerm2, VS Code, Cursor, etc.)5733. Enable **Allow Notifications** and choose **Banners** or **Alerts**5744. Ensure **Focus** / Do Not Disturb is not blocking notifications575576Use `check_notification_setup` to diagnose and `test_notification` to verify.577</details>578579<details>580<summary>Linux</summary>581582Requires `notify-send` from `libnotify`. For sound alerts, `paplay` is also needed:583584```bash585# Ubuntu / Debian586sudo apt install libnotify-bin pulseaudio-utils587588# Fedora589sudo dnf install libnotify pulseaudio-utils590591# Arch592sudo pacman -S libnotify593```594595Desktop notifications require a running display server (X11/Wayland) — they will not work in headless/SSH sessions.596</details>597598<details>599<summary>Windows</summary>600601Uses PowerShell toast notifications (built-in):6026031. Open **Settings → System → Notifications**6042. Ensure **Notifications** is turned on6053. Set **Focus Assist** to allow notifications6064. If using Windows Terminal, ensure its notifications are enabled607</details>608609**AI-configurable:** The AI can check, test, and configure notifications at runtime:610- `check_notification_setup` — diagnose platform support and show setup instructions611- `test_notification` — send a test notification to verify everything works612- `configure_alerts` — enable/disable desktop, sound, threshold, webhook (with optional persist to config file)613614**Webhook payload:**615```json616{617 "event": "email.urgent",618 "account": "work",619 "sender": { "name": "John CEO", "address": "ceo@company.com" },620 "subject": "Q4 Review Due Today",621 "priority": "urgent",622 "labels": ["VIP"],623 "rule": "VIP Contacts",624 "timestamp": "2026-02-18T11:30:00Z"625}626```627628Static rules can force desktop notifications with `alert = true`, regardless of urgency threshold:629```toml630[[settings.hooks.rules]]631name = "VIP Contacts"632match = { from = "ceo@company.com" }633actions = { flag = true, alert = true, labels = ["VIP"] }634```635636Features:637- **Auto-reconnect** — Exponential backoff (1s → 60s) on connection failures638- **Batching** — Groups arrivals within a configurable delay to reduce AI calls639- **Rate limiting** — Max 10 sampling calls per minute640- **Graceful degradation** — Falls back to notify mode if client doesn't support sampling641- **Resource subscriptions** — Pushes `notifications/resources/updated` for unread counts642643## API644645### Tools (47)646647#### Read (14)648649| Tool | Description |650|------|-------------|651| `list_accounts` | List all configured email accounts |652| `list_mailboxes` | List folders with unread counts and special-use flags |653| `list_emails` | Paginated email listing with date, sender, subject, and flag filters |654| `get_email` | Read full email content with attachment metadata |655| `get_emails` | Fetch full content of multiple emails in a single call (max 20) |656| `get_email_status` | Get read/flag/label state of an email without fetching the body |657| `search_emails` | Search by keyword across subject, sender, and body |658| `download_attachment` | Download an email attachment by filename |659| `find_email_folder` | Discover the real folder(s) an email resides in (resolves virtual folders) |660| `extract_contacts` | Extract unique contacts from recent email headers |661| `get_thread` | Reconstruct a conversation thread via References/In-Reply-To |662| `list_templates` | List available email templates |663| `get_email_stats` | Email analytics — volume, top senders, daily trends |664| `check_health` | Connection health, latency, quota, and IMAP capabilities |665666#### Write (9)667668| Tool | Description |669|------|-------------|670| `send_email` | Send a new email (plain text or HTML, CC/BCC) |671| `reply_email` | Reply with proper threading (In-Reply-To, References) |672| `forward_email` | Forward with original content quoted |673| `save_draft` | Save an email draft to the Drafts folder |674| `send_draft` | Send an existing draft and remove from Drafts |675| `apply_template` | Apply a template with variable substitution |676| `schedule_email` | Schedule an email for future delivery |677| `list_scheduled` | List scheduled emails by status |678| `cancel_scheduled` | Cancel a pending scheduled email |679680#### Manage (7)681682| Tool | Description |683|------|-------------|684| `move_email` | Move email between folders |685| `delete_email` | Move to Trash or permanently delete |686| `mark_email` | Mark as read/unread, flag/unflag |687| `bulk_action` | Batch operation on up to 100 emails |688| `create_mailbox` | Create a new mailbox folder |689| `rename_mailbox` | Rename an existing mailbox folder |690| `delete_mailbox` | Permanently delete a mailbox and contents |691692#### Labels (5)693694| Tool | Description |695|------|-------------|696| `list_labels` | Discover available labels (auto-detects provider strategy) |697| `add_label` | Add a label to an email (ProtonMail folders, Gmail X-GM-LABELS, or IMAP keywords) |698| `remove_label` | Remove a label from an email |699| `create_label` | Create a new label |700| `delete_label` | Delete a label |701702#### Watcher & Alerts (6)703704| Tool | Description |705|------|-------------|706| `get_watcher_status` | Show IMAP IDLE connections, folders being monitored, and last-seen UIDs |707| `list_presets` | List available AI triage presets with descriptions and suggested labels |708| `get_hooks_config` | Show current hooks configuration — preset, rules, and custom instructions |709| `configure_alerts` | Update alert/notification settings at runtime |710| `check_notification_setup` | Diagnose desktop notification support and provide setup instructions |711| `test_notification` | Send a test notification to verify OS permissions are configured |712713#### Calendar & Reminders (6)714715| Tool | Description |716|------|-------------|717| `extract_calendar` | Extract ICS/iCalendar events from an email |718| `analyze_email_for_scheduling` | Analyze an email to detect events and reminder-worthy content |719| `add_to_calendar` | Add an email event to the local calendar (macOS/Linux) |720| `create_reminder` | Create a reminder in macOS Reminders.app from an email |721| `list_calendars` | List all available local calendars |722| `check_calendar_permissions` | Check whether the local calendar is accessible |723724### Prompts (7)725726| Prompt | Description |727|--------|-------------|728| `triage_inbox` | Categorize and prioritize unread emails with suggested actions |729| `summarize_thread` | Summarize an email conversation thread |730| `compose_reply` | Draft a context-aware reply to an email |731| `draft_from_context` | Compose a new email from provided context and instructions |732| `extract_action_items` | Extract actionable tasks from email threads |733| `summarize_meetings` | Summarize upcoming calendar events from emails |734| `cleanup_inbox` | Suggest emails to archive, delete, or unsubscribe from |735736### Resources (6)737738| Resource | URI | Description |739|----------|-----|-------------|740| Accounts | `email://accounts` | List of configured accounts |741| Mailboxes | `email://{account}/mailboxes` | Folder tree for an account |742| Unread | `email://{account}/unread` | Unread email summary |743| Templates | `email://templates` | Available email templates |744| Stats | `email://{account}/stats` | Email statistics snapshot |745| Scheduled | `email://scheduled` | Pending scheduled emails |746747### Provider Auto-Detection748749| Provider | Domains |750|----------|---------|751| Gmail | gmail.com |752| Outlook / Hotmail | outlook.com, hotmail.com, live.com |753| Yahoo Mail | yahoo.com, ymail.com |754| iCloud | icloud.com, me.com, mac.com |755| Fastmail | fastmail.com |756| ProtonMail Bridge | proton.me, protonmail.com |757| Zoho Mail | zoho.com |758| GMX | gmx.com, gmx.de, gmx.net |759760### Architecture761762```763src/764├── main.ts — Entry point and subcommand routing765├── server.ts — MCP server factory766├── logging.ts — MCP protocol logging bridge767├── cli/ — Interactive CLI commands768│ ├── account-commands.ts — Account CRUD (list, add, edit, delete)769│ ├── setup.ts — Legacy setup alias → account add770│ ├── test.ts — Connection tester771│ ├── config-commands.ts — Config management (show, edit, path, init)772│ ├── install-commands.ts — MCP client registration (install, status, remove)773│ ├── providers.ts — Provider auto-detection + OAuth2 endpoints (experimental)774│ └── scheduler.ts — Scheduler CLI775├── config/ — Configuration layer776│ ├── xdg.ts — XDG Base Directory paths777│ ├── schema.ts — Zod validation schemas778│ └── loader.ts — Config loader (TOML + env vars)779├── connections/780│ └── manager.ts — Lazy persistent IMAP/SMTP with OAuth2 (experimental)781├── services/ — Business logic782│ ├── imap.service.ts — IMAP operations783│ ├── label-strategy.ts — Provider-aware label strategy (ProtonMail/Gmail/IMAP keywords)784│ ├── smtp.service.ts — SMTP operations785│ ├── template.service.ts — Email template engine786│ ├── oauth.service.ts — OAuth2 token management (experimental)787│ ├── calendar.service.ts — ICS/iCalendar parsing788│ ├── scheduler.service.ts — Email scheduling queue789│ ├── watcher.service.ts — IMAP IDLE real-time watcher with auto-reconnect790│ ├── hooks.service.ts — AI triage via MCP sampling + static rules + auto-labeling/flagging791│ ├── notifier.service.ts — Multi-channel notification dispatcher (desktop/sound/webhook)792│ ├── presets.ts — Built-in hook presets (inbox-zero, gtd, priority-focus, etc.)793│ └── event-bus.ts — Typed EventEmitter for internal email events794├── tools/ — MCP tool definitions (42)795├── prompts/ — MCP prompt definitions (7)796├── resources/ — MCP resource definitions (6)797├── safety/ — Audit trail and rate limiter798└── types/ — Shared TypeScript types799```800801## Maintainers802803[@codefuturist](https://github.com/codefuturist)804805## Contributing806807PRs accepted. Please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification when editing this README.808809```bash810# Development workflow811pnpm install812pnpm typecheck # type check813pnpm check # lint and format814pnpm build # build815pnpm start # run816```817818## License819820[LGPL-3.0-or-later](LICENSE)821
Full transparency — inspect the skill content before installing.