Email MCP

Delete an email. By default moves to Trash. Set permanent=true for permanent deletion (⚠️ irreversible). The mailbox must be a real folder. Use find_email_folder first if the email was found in a virtual folder.

Delete a label. For ProtonMail, deletes the label folder. For standard IMAP keywords, labels cannot be deleted server-wide — use remove_label on individual emails.

⚠️ DESTRUCTIVE: Permanently delete a mailbox and ALL its contents. This cannot be undone. Use list_mailboxes to verify the folder path.

Description is built at runtime.

Extract calendar events (ICS/iCalendar) from an email. Returns structured event data including time, location, attendees, and status.

Extract unique contacts from recent email headers. Returns contacts sorted by frequency (most frequent first). Useful for finding frequent correspondents or building an address book.

Find a real mailbox folder an email belongs to. Required before move_email or delete_email when the email was found in a virtual folder (e.g., "All Mail", "Starred"). Returns the first real folder path found, to use as sourceMailbox; on a label-based server a message may also sit in other folders.

Forward an email to new recipients with optional additional message. The original is converted to readable text and "> "-quoted below your note; its attachments are re-attached unless includeAttachments is false. Set html=true to also send an HTML part carrying the original HTML in a blockquote.

Description is built at runtime.

Get email statistics and analytics for a mailbox. Shows volume, top senders, daily trends, and read/flagged counts.

Get the current read/flag/label state of an email without fetching its body. Much cheaper than get_email when you only need to check whether an email is unread, flagged, or which labels it has. Also useful to confirm the result of a mark_email call. Does NOT mark the email as seen.

Fetch the full content of multiple emails in a single call (max 20). More efficient than calling get_email repeatedly when triaging or summarising several emails. Does NOT mark emails as seen. Defaults to format="text" (HTML stripped) for compact, AI-friendly output. Each message carries the same 📰 newsletter / 🤖 automated marker as get_email.

Get the current AI hooks configuration including preset, rules, and custom instructions.

Description is built at runtime.

Find the newest verification code (OTP/2FA) or sign-in magic link in recent mail, using false-positive-resistant scoring (EN/DE). Use wait_seconds (max 45) to wait for a mail still in flight; if nothing arrives, simply call again. Works without the watcher via polling — with [settings.watcher] enabled, hits land within ~1 second. Set copy_to_clipboard=true to also place the value on the clipboard (concealed from clipboard managers, auto-cleared). The code/link is returned in the result by design.

Get the status of IMAP IDLE watcher connections and recent activity.

List all configured email accounts. Call this first to discover available account names for use with other tools.

List all available local calendars (macOS Calendar.app / Linux default). Use the returned calendar names with add_to_calendar to target a specific calendar.

List emails in a mailbox with optional filters. Returns paginated results with metadata (read/unread 🔵, flagged ⭐, replied ↩️, attachments 📎, labels 🏷️). List or machine-generated mail is marked 📰 newsletter / 🤖 automated from its RFC headers, with the unsubscribe URI when the sender offers one — personal mail carries no marker. Use get_email to fetch full body content. ProtonMail note: labels are represented as IMAP folders — use list_labels to discover them, then list_emails with mailbox="Labels/X" to find labeled emails.

List local calendar events with optional filters. Search by title, date range, or calendar name. Use to check for existing events before creating new ones, or to verify a recently added event. Returns event id, title, start/end time, location, and calendar name.

List available labels for an email account. Auto-detects the label system: ProtonMail folder-labels, Gmail X-GM-LABELS, or IMAP keywords. ProtonMail note: labels are represented as IMAP folders under the Labels/ prefix. Use list_emails with mailbox="Labels/<name>" to find emails tagged with a ProtonMail label.

List all mailbox folders for an account with unread counts and special-use flags. Use list_accounts first to get the account name.

List all available AI triage presets with their descriptions and suggested labels.

List reminders from macOS Reminders.app with optional filters. Search by title or list name. By default only shows incomplete reminders. Use to check for existing reminders before creating new ones, or to verify a recently added reminder. Returns reminder id, title, due date, completion status, priority, and list name.

List scheduled emails. Shows pending, sent, or all scheduled emails.

List all available email templates. Templates are TOML files in ~/.config/email-mcp/templates/ with {{variable}} placeholders for subject and body.

Change email flags — mark as read/unread, flag/unflag. Idempotent: marking an already-read email as read is a no-op.

Move an email to a different mailbox folder. The sourceMailbox must be a real folder, not a virtual one like "All Mail". Use find_email_folder first if the email was discovered in a virtual folder.

Remove a label from an email. For ProtonMail, this removes the email from the label folder. For Gmail and standard IMAP, this removes a keyword flag.

Rename an existing mailbox (folder). Use list_mailboxes to see current folder paths.

Reply to an email with proper threading (In-Reply-To & References headers). Use get_email first to read the original. The original message is quoted below the reply by default (Thunderbird/Outlook style) — set quoteOriginal=false for the bare body only.

Save an email draft to the Drafts folder. Compose over time, then use send_draft to send it. Use list_emails with the Drafts mailbox to see saved drafts.

Schedule an email to be sent at a specific time in the future. The email is queued locally and sent automatically when the time arrives.

Search emails by keyword across subject, sender, and body — and, where the local mirror is enabled, attachment filenames (searching "report" finds an email carrying Q3-report.pdf). Omit query (or pass an empty string) to use it as a pure filter — e.g. find all emails from a specific sender without a keyword. Supports additional filters for sender, recipient, date range (since/before — INTERNALDATE; sent_since/sent_before — Date: header), attachments, size, and reply status. At least one of query/from/to/since/before/sent_since/sent_before/has_attachment/larger_than/smaller_than/answered must b…

Send an existing draft email and remove it from Drafts. The draft is fetched, sent via SMTP, then deleted. Use list_emails with the Drafts mailbox to find draft IDs.

Send a new email. Supports plain text or HTML body, CC, and BCC.

Send a test desktop notification to verify that OS permissions are correctly configured. Use check_notification_setup first to diagnose any issues.