Skip to main content
Glama
Enterprise Mail MCP Server

Enterprise Mail MCP Server

by yusuf-polat

πŸ“¬ Enterprise Mail MCP Server

Model Context Protocol TypeScript Node.js Security License: MIT

An enterprise-ready, autonomous Model Context Protocol (MCP) server that connects Large Language Model (LLM) agentsβ€”including Antigravity IDE, Claude Desktop, and other MCP-compliant clientsβ€”to email accounts via standard IMAP and SMTP protocols.

Equipped with autonomous mailbox triage, thread-aware smart drafting, RFC 5545 calendar event generation, marketing unsubscribe link detection, and a zero-trust multi-layer antivirus engine that scans all attachments before disk persistence.


🌟 Key Capabilities

πŸ›‘οΈ Zero-Trust Security, Sanitization & Antivirus Protection

  • HTML/CSS Zero-Day & PortSwigger Exploit Neutralization: Automatically detects and strips dangerous CSS font exfiltration (@font-face, unicode-range, descent-override), Label Hijacking (<label for="..."> attacking webmail UI buttons), and remote IP tracking (image-set(), @import, remote stylesheets).

  • AI Prompt Injection & Steganography Shield: Detects stealth text hidden via CSS (opacity: 0, font-size: 0, display: none, ::before/::after pseudo-elements) intended to deceive AI readers, and blocks indirect prompt injection payloads attempting to compromise credentials.

  • Outbound Data Loss Prevention (DLP): Monitors all outgoing messages (send_email, reply_email) to guarantee environment secrets (e.g. IMAP_PASS, SMTP_PASS, API tokens) can never be exfiltrated via email.

  • Mandatory Antivirus Scanning: Every file attachment requested for download is first isolated in a secure quarantine staging area (.quarantine/) and scanned by Microsoft Defender Antivirus (MpCmdRun.exe) and heuristic engines.

  • Malware & Double Extension Defense: Detects executable tricks (.pdf.exe, .docx.scr), script blocks, and standard malware signatures.

  • Instant Destruction on Threat: Any flagged attachment is immediately expunged from storage and blocked with a VirusThreatDetectedError. Safe files are verified with SHA-256 hashes.

πŸ“¬ Complete Mailbox Operations & Organization

  • Read & Search: List recent emails (check_inbox), search with multi-criteria filters (search_emails), and inspect complete MIME details (read_email).

  • Folder & Label Management: Enumerate mailboxes (list_folders), move messages between folders (move_email), star/flag/read-unread (flag_email), and safely trash or delete (delete_email).

  • Attachment Downloader: Verified, secure attachment extraction (download_attachment).

✍️ Intelligent Dispatch & Smart Drafts

  • Direct Send & Reply: RFC 2822-compliant message delivery with HTML, CC, BCC, and thread-aware headers (In-Reply-To, References).

  • Non-Destructive AI Drafts (create_draft): Generates proposed emails directly inside the server's Drafts folder, allowing human-in-the-loop review before sending.

🧠 Semantic Email Intelligence & Triage

  • Heuristic Analysis (analyze_email): Computes urgency scores (0–100), extracts action items, classifies intent (BILLING_INVOICE, SECURITY_ALERT, SUPPORT, etc.), detects financial entities, and checks phishing indicators.

  • Autonomous Inbox Triage (triage_inbox): Scans the latest messages and compiles an executive triage report highlighting critical tasks, pending payments, security events, and newsletters.

πŸ“… Calendar & Productivity Tools

  • Meeting Extractor (extract_calendar_event): Parses dates, times, attendees, and virtual meeting links (Google Meet, Zoom, Microsoft Teams) to generate RFC 5545 standard .ics iCalendar payloads.

  • Unsubscribe Assistant (find_unsubscribe_links): Extracts RFC 2369 List-Unsubscribe headers (one-click URLs and mailto) along with in-body unsubscribe links.

  • Real-Time Notification (watch_new_emails): Leverages IMAP IDLE for instant arrival notifications without polling overhead.


Related MCP server: mcp-imap

πŸ—οΈ Architecture Overview

                          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                          β”‚   LLM Agent / MCP Client   β”‚
                          β”‚ (Antigravity / Claude / AI)β”‚
                          β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                        β”‚  JSON-RPC (stdio)
                                        β–Ό
                          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                          β”‚    Mail MCP Core Server    β”‚
                          β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜
                                 β”‚              β”‚
           β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
           β”‚   IMAP / SMTP Services  β”‚     β”‚ Security & Intelligence β”‚
           β”‚ (ImapFlow & Nodemailer) β”‚     β”‚ (Analyzer & Antivirus)  β”‚
           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                         β”‚                      β”‚
        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”      β”œβ”€β–Ί Microsoft Defender (MpCmdRun)
        β”‚  Mail Providers (TLS / SSL)    β”‚      β”œβ”€β–Ί Double-Extension Defense
        β”‚  β€’ Gmail                       β”‚      β”œβ”€β–Ί EICAR & Heuristic Checks
        β”‚  β€’ Microsoft Outlook / 365     β”‚      β”œβ”€β–Ί Quarantine Staging Area
        β”‚  β€’ Custom IMAP/SMTP Servers    β”‚      └─► SHA-256 Hash Verification
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ› οΈ Tool Catalog Reference

Tool Name

Scope

Description

check_inbox

Reading

Retrieves recent message headers with pagination and unread filtering.

search_emails

Reading

Searches emails by query, sender, recipient, subject, body, or dates.

read_email

Reading

Fetches and parses complete MIME email details (HTML, text, headers, attachments).

list_folders

Organization

Lists all account mailboxes, special-use flags, and paths.

move_email

Organization

Moves an email by UID to a destination folder or label.

flag_email

Organization

Adds, removes, or sets IMAP flags (\Flagged, \Seen, etc.).

delete_email

Organization

Moves message to Trash or permanently purges it.

download_attachment

Attachments

Scans with Windows Defender and saves verified attachments to disk.

send_email

Dispatch

Sends a new email via SMTP with HTML/Text support.

reply_email

Dispatch

Replies to an existing thread maintaining message references.

create_draft

Dispatch

Saves an email draft to the Drafts folder for manual review.

verify_smtp_connection

Diagnostic

Validates SMTP server credentials and connectivity.

analyze_email

Intelligence

Computes urgency, intent, sentiment, action items, and security warnings.

triage_inbox

Intelligence

Audits recent inbox activity into grouped actionable categories.

extract_calendar_event

Calendar

Converts meeting text/dates/links into standard .ics format.

find_unsubscribe_links

Unsubscribe

Identifies List-Unsubscribe headers and opt-out links.

watch_new_emails

Monitoring

Holds an IMAP IDLE connection to wait for incoming mail.

check_for_updates

Management

Checks and syncs with latest GitHub master security patches and releases.


πŸš€ Getting Started

1. Prerequisites

  • Node.js: v20.0.0 or higher

  • Package Manager: npm (v9+)

  • An active email account supporting IMAP/SMTP (e.g. Gmail, Outlook, Yahoo, or private webmail)

2. Installation

git clone https://github.com/yusuf-polat/mail-mcp.git
cd mail-mcp
npm install

3. Environment Configuration

Copy the provided .env.example file to .env:

cp .env.example .env

Edit .env with your email account configuration:

# --- IMAP Configuration (Reading & Real-Time Monitoring) ---
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
IMAP_USER=your_email@example.com
IMAP_PASS=your_16_digit_app_password

# --- SMTP Configuration (Sending & Replying) ---
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=your_email@example.com
SMTP_PASS=your_16_digit_app_password

# --- Sender Info ---
SMTP_FROM_NAME="AI Mail Assistant"
# SMTP_FROM_ADDRESS=your_email@example.com

# --- Debug Mode ---
DEBUG=false
IMPORTANT

Gmail Users: Do not use your personal password. Enable 2-Step Verification on your Google Account, generate a 16-character App Password, and verify that IMAP Access is enabled.

4. Build

Compile TypeScript to production-ready JavaScript in dist/:

npm run build

5. Verification Test

Validate that the services, MIME parsers, and heuristic analyzer initialize properly:

npx tsx test/smoke.test.ts

πŸ”Œ MCP Client Integration

Antigravity IDE

Add the server definition to %USERPROFILE%\.gemini\config\mcp_config.json (Windows) or ~/.gemini/config/mcp_config.json (macOS / Linux):

{
  "mcpServers": {
    "mail": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mail-mcp\\dist\\index.js"
      ]
    }
  }
}

Claude Desktop

Add the server definition to your claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mail": {
      "command": "node",
      "args": [
        "/absolute/path/to/mail-mcp/dist/index.js"
      ]
    }
  }
}

πŸ”’ Security and Privacy Best Practices

  1. Strict Secrets Isolation: The .env file is excluded via .gitignore. Never commit credentials, tokens, or app passwords to version control.

  2. Read-Only Option: If sending or message deletion capabilities are not required in your environment, permissions can be restricted at the mail provider level.

  3. Quarantine Execution: Downloaded attachments are placed in .quarantine/ and scanned prior to delivery.

  4. Draft-First Workflows: For critical correspondence, use create_draft instead of send_email to maintain human review.


πŸ“„ License

This project is licensed under the MIT License.

Available Tools

17 tools
analyze_emailA

Bir e-postanın içeriğini derinlemesine analiz eder: aciliyet derecesi, niyet/kategori, ton/duygu, aksiyon maddeleri, tarihler, para tutarları, âzet ve phishing/spam riskleri.

Inputs: uid, folder, subject, bodyText.

check_inboxB

Gelen kutusundaki (veya belirtilen klasΓΆrdeki) en son e-postalarΔ± ΓΆzet bilgilerle listeler.

Inputs: limit, folder, unreadOnly.

create_draftA

E-postayı hemen gândermez; Taslaklar (Drafts) klasârüne yapay zeka tarafından oluşturulmuş bir taslak olarak kaydeder.

Inputs: subject (required), bodyText (required), cc, to, +3 more.

delete_emailB

E-postayı çâp kutusuna taşır veya kalıcı olarak siler.

Inputs: uid (required), folder, permanent.

download_attachmentA

Belirtilen e-postadaki eki indirir. GÜVENLİK ZORUNLULUĞU: Dosya kesinlikle indirilmeden ânce Windows Defender ve çok katmanlı sezgisel virüs taramasından geçirilir. Tehdit bulunursa dosya derhal imha edilir ve indirme iptal edilir.

Inputs: uid (required), attachmentIdentifier (required), folder, targetDir.

extract_calendar_eventB

E-postadaki toplantΔ±, randevu ve etkinlik bilgilerini (tarih, saat, link, katΔ±lΔ±mcΔ±lar) Γ§Δ±karΔ±r ve standart .ics (iCalendar) formatΔ± ΓΌretir.

Inputs: uid, folder, subject, bodyText.

flag_emailA

E-postaya bayrak ekler, kaldΔ±rΔ±r veya gΓΌnceller (ΓΆrn: yΔ±ldΔ±zlama '\Flagged', okundu '\Seen').

Inputs: uid (required), flags (required), action, folder.

list_foldersB

Posta kutusundaki tΓΌm klasΓΆrleri, etiketleri ve ΓΆzel kullanΔ±m yollarΔ±nΔ± listeler.

Inputs: no named parameters.

move_emailB

Belirtilen e-postayı (UID) hedef klasâre veya etikete taşır.

Inputs: uid (required), destinationFolder (required), sourceFolder.

read_emailC

UID numarası verilen belirli bir e-postayı gâvdesi, ek bilgileri ve başlıklarıyla eksiksiz okur.

Inputs: uid (required), folder, markAsSeen.

reply_emailA

Gelen bir e-postaya RFC standartlarına uygun başlıklar (In-Reply-To, References, Re:) ve orijinal alıntıyla yanıt verir.

Inputs: bodyText (required), originalUid (required), folder, bodyHtml, +1 more.

search_emailsC

Gelişmiş arama kriterleri ile e-postaları arar (gânderen, konu, gâvde, tarih, okunmamışlık vb.).

Inputs: to, from, limit, query, +5 more.

send_emailC

Belirtilen alΔ±cΔ±(lar)a yeni bir e-posta gΓΆnderir.

Inputs: to (required), subject (required), bodyText (required), cc, +3 more.

triage_inboxA

Gelen kutusundaki son e-postaları topluca tarar, ânem derecesine gâre gruplar (Güvenlik, Finans, Acil Gârevler, Bültenler) ve eyleme dânüştürülebilir âzet rapor sunar.

Inputs: limit, folder.

verify_smtp_connectionA

SMTP sunucu yapılandırmasını ve bağlantısını test eder.

Inputs: no named parameters.

watch_new_emailsB

IMAP IDLE protokolünü kullanarak gelen kutusunu anlık olarak dinler. Yeni bir e-posta düştüğü anda veya zaman aşımı süresi dolduğunda sonucu dâner.

Inputs: folder, timeoutSeconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing, searching, reading, sending, replying, drafting, real-time watching, analyzing, triaging, folders, moving, flagging, deleting, attachments, and calendar extraction do not meaningfully overlap. Even similarly scoped tools like check_inbox, search_emails, and triage_inbox are differentiated by intent and output.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern such as check_inbox, send_email, move_email, and delete_email. This makes the API predictable and easy to navigate for an agent.

    Tool Count4/5

    At 17 tools, the server is slightly above the ideal 3-15 range but every tool appears to serve a legitimate mail-related function. The count is reasonable for a broad enterprise mail feature set and does not feel bloated.

    Completeness4/5

    The tool surface covers core email workflows: send, reply, draft, read, search, delete, move, flag, attachment download, folder listing, and real-time monitoring. Minor gaps exist, such as no explicit forward_email tool, no folder creation/management, and no clearly described attachment support when sending or creating drafts.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to read, search, compose, and send emails by connecting to any IMAP/SMTP provider. It supports comprehensive mailbox management, including draft handling and message deletion, directly through natural language.
      10
      206 npm
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to read, send, organize, and search emails across multiple IMAP/SMTP mailboxes.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to read, search, send, and manage emails via IMAP/SMTP with OAuth 2.1 authentication, supporting folders, drafts, replies, and forwarding.
      1
      MIT