# codefuturist/email-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/codefuturist/email-mcp  
**GitHub Stars:** 109  
**npm Downloads (last month):** 22130  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codefuturist-email-mcp

## Description
IMAP/SMTP email MCP server with 42 tools for reading, searching, sending, scheduling, and managing emails across multiple accounts. Supports IMAP IDLE push, AI triage, desktop notifications, and auto-detects providers like Gmail, Outlook, and iCloud.

## Tools
Capabilities this server exposes over MCP:

- **list_accounts** — List all configured email accounts
- **list_mailboxes** — List folders with unread counts and special-use flags
- **list_emails** — Paginated email listing with date, sender, subject, and flag filters
- **get_email** — Read full email content with attachment metadata
- **get_emails** — Fetch full content of multiple emails in a single call (max 20)
- **get_email_status** — Get read/flag/label state of an email without fetching the body
- **search_emails** — Search by keyword across subject, sender, and body
- **download_attachment** — Download an email attachment by filename
- **find_email_folder** — Discover the real folder(s) an email resides in (resolves virtual folders)
- **extract_contacts** — Extract unique contacts from recent email headers
- **get_thread** — Reconstruct a conversation thread via References/In-Reply-To
- **list_templates** — List available email templates
- **get_email_stats** — Email analytics — volume, top senders, daily trends
- **check_health** — Connection health, latency, quota, and IMAP capabilities
- **send_email** — Send a new email (plain text or HTML, CC/BCC)
- **reply_email** — Reply with proper threading (In-Reply-To, References)
- **forward_email** — Forward with original content quoted
- **save_draft** — Save an email draft to the Drafts folder
- **send_draft** — Send an existing draft and remove from Drafts
- **apply_template** — Apply a template with variable substitution
- **schedule_email** — Schedule an email for future delivery
- **list_scheduled** — List scheduled emails by status
- **cancel_scheduled** — Cancel a pending scheduled email
- **move_email** — Move email between folders
- **delete_email** — Move to Trash or permanently delete
- **mark_email** — Mark as read/unread, flag/unflag
- **bulk_action** — Batch operation on up to 100 emails
- **create_mailbox** — Create a new mailbox folder
- **rename_mailbox** — Rename an existing mailbox folder
- **delete_mailbox** — Permanently delete a mailbox and contents
- **list_labels** — Discover available labels (auto-detects provider strategy)
- **add_label** — Add a label to an email (ProtonMail folders, Gmail X-GM-LABELS, or IMAP keywords)
- **remove_label** — Remove a label from an email
- **create_label** — Create a new label
- **delete_label** — Delete a label
- **get_watcher_status** — Show IMAP IDLE connections, folders being monitored, and last-seen UIDs
- **list_presets** — List available AI triage presets with descriptions and suggested labels
- **get_hooks_config** — Show current hooks configuration — preset, rules, and custom instructions
- **configure_alerts** — Update alert/notification settings at runtime
- **check_notification_setup** — Diagnose desktop notification support and provide setup instructions
- **test_notification** — Send a test notification to verify OS permissions are configured
- **extract_calendar** — Extract ICS/iCalendar events from an email
- **analyze_email_for_scheduling** — Analyze an email to detect events and reminder-worthy content
- **add_to_calendar** — Add an email event to the local calendar (macOS/Linux)
- **create_reminder** — Create a reminder in macOS Reminders.app from an email
- **list_calendars** — List all available local calendars
- **check_calendar_permissions** — Check whether the local calendar is accessible

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "email-mcp": {
    "command": "npx",
    "args": ["-y","@codefuturist/email-mcp"],
    "env": {
      "MCP_EMAIL_ADDRESS": "",
      "MCP_EMAIL_PASSWORD": "",
      "MCP_EMAIL_IMAP_HOST": "",
      "MCP_EMAIL_SMTP_HOST": "",
      "EMAIL_ACCOUNTS": ""
    }
  }
}
```

**Requires environment variables:** `MCP_EMAIL_ADDRESS`, `MCP_EMAIL_PASSWORD`, `MCP_EMAIL_IMAP_HOST`, `MCP_EMAIL_SMTP_HOST`, `EMAIL_ACCOUNTS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What codefuturist/email-mcp MCP server does

The codefuturist/email-mcp MCP server exposes email operations over Model Context Protocol for accounts that support IMAP and SMTP. It can inspect folders and unread counts, list or search messages, retrieve full message content, inspect status flags, download attachments, reconstruct threads, and extract contacts from recent headers.

The server also covers outbound and organizational workflows. Agents can send new messages, reply with threading headers, forward existing content, save and send drafts, apply templates, schedule future delivery, and cancel scheduled messages. Mail can be moved, deleted, marked read or unread, flagged, or processed in bulk. Mailbox creation, renaming, and deletion are also available.

## How it works

Connections use IMAP for mailbox access and SMTP for sending. Multiple accounts can be configured and operated through the same MCP server. Provider settings can be detected for services including Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX, and ProtonMail as listed by the project.

The server uses stdio transport. It stores its default configuration in the XDG-style path `~/.config/email-mcp/config.toml`, while a single account can alternatively be supplied through environment variables. A setup wizard can detect server settings, test connections, save configuration, and produce an MCP client configuration snippet.

Additional functions include message statistics, connection health checks, scheduled-message management, template variable substitution, and provider-aware label handling. The README also describes an IMAP IDLE watcher, AI triage with presets and rules, desktop or webhook alerts, and calendar extraction from ICS content.

## Setup and configuration

The codefuturist/email-mcp MCP server requires Node.js 22 or newer when run with its npm package. The directly runnable MCP configuration is:

```json
{
  "command": "npx",
  "args": ["-y", "@codefuturist/email-mcp", "stdio"]
}
```

Before starting the MCP process, create an account configuration with `npx @codefuturist/email-mcp setup`, or use the CLI commands `email-mcp account add` and `email-mcp config init`. The setup flow is recommended for interactive account creation and connection testing. Docker is also supported; the host configuration directory must be mounted into the container because the transport remains stdio.

For a single account without a configuration file, the documented variables are `MCP_EMAIL_ADDRESS`, `MCP_EMAIL_PASSWORD`, `MCP_EMAIL_IMAP_HOST`, and `MCP_EMAIL_SMTP_HOST`. Gmail and Microsoft 365 OAuth2 authentication is described as experimental.

## Tools and capabilities

The exposed operations include:

- Browse mailboxes and paginated messages with sender, date, subject, and flag filters.
- Read one or multiple messages, inspect status, search content, resolve folders, and reconstruct threads.
- Send, reply to, forward, draft, template, schedule, cancel, and bulk-process email.
- Download attachments, with downloads capped at 5 MB and returned as base64.
- Create, rename, delete, and move through mailbox folders.
- Extract contacts and produce email volume, sender, and daily-trend statistics.
- Check connection health, latency, quota, and IMAP capabilities.

## Limitations and notes

The codefuturist/email-mcp MCP server requires valid email account access and does not replace the provider’s IMAP or SMTP permissions. OAuth2 support is experimental rather than documented as the default authentication path. Attachments larger than 5 MB cannot be downloaded through the documented attachment operation.

Connections use TLS or STARTTLS, passwords are not logged, and an audit trail records operations without credentials. A configurable token-bucket rate limiter applies per account. Configuration should be created on the host before using the Docker image, and the mounted configuration directory is shown as read-only in the example.

_Full upstream README: https://allmcps.com/mcp/codefuturist-email-mcp/readme_