Skip to main content
Glama

Email MCP Server

A full-featured email server for MCP clients. Send and receive mail through SMTP/IMAP, transactional APIs (SendGrid, Mailgun, Resend), local test servers (MailHog), and webhooks (Slack, Discord). Includes a web dashboard with AI-assisted compose, a throwaway SMTP lab, folder management, contact import, background mail watching, and creative AI workflows (love letters, complaints, ASCII art, SVG cards).

v0.4.1 -- 188 tests passing, 42 MCP tools, FastMCP 3.4+, dual transport (stdio + HTTP).


Quick Start

.\start.ps1

Opens the web dashboard at http://localhost:10812. Backend runs on port 10813.

Requirements: Python 3.12+, uv. Start configuring services from the Settings page.

For Claude Desktop setup, MCPB packaging, and manual configuration see docs/quickstart.md.

Related MCP server: io.github.p-w-4-z/inbox-mcp

Supported Email Systems

Type

Providers

Guide

Microsoft Graph

Personal Outlook/Hotmail (basic SMTP/IMAP auth disabled)

docs/outlook.md

SMTP/IMAP

Gmail, Outlook/M365, Yahoo, iCloud, ProtonMail

docs/gmail.md, docs/outlook.md, docs/protonmail.md

Transactional APIs

SendGrid, Mailgun, Resend, Amazon SES

docs/api-services.md

Local Testing

MailHog, Mailpit, MailCatcher, Inbucket

docs/local-testing.md

Webhooks

Slack, Discord, Telegram

docs/webhook-integrations.md

Documentation

Document

Contents

docs/quickstart.md

Installation, Claude Desktop setup, first email

docs/configuration.md

All env vars, mailing lists, dynamic config

docs/TOOLS.md

Full 39-tool reference with REST surface

docs/DEVELOPMENT.md

Architecture, commands, contribution patterns

docs/TROUBLESHOOTING.md

Symptom lookup, diagnostics endpoints

docs/safety-hardening.md

Prompt injection defense architecture

docs/mail-watcher.md

Background IMAP polling + webhook notifications

docs/robofang-integration.md

Integrate with robofang for TTS/light alerts

docs/gmail.md

Gmail app password setup

docs/outlook.md

Outlook/Hotmail — Graph API (OAuth) + SMTP/IMAP

docs/connectors.md

aiwatcher + robofang fleet event connectors

docs/protonmail.md

ProtonMail Bridge & direct access

docs/api-services.md

SendGrid, Mailgun, Resend, SES

docs/local-testing.md

MailHog, Mailpit for dev

docs/webhook-integrations.md

Slack, Discord, Telegram

Features

  • 42 MCP tools: send, receive, search, delete, move, copy, forward, mark-read, folder CRUD, manage email services, contacts, auto-respond, workflows, mail lab, fleet connectors

  • Web dashboard: full React SPA at localhost:10812

  • Microsoft Graph support: send/receive for personal Outlook/Hotmail via Graph REST API (OAuth device flow, public client ID — no Azure registration)

  • Folder treeview: expandable sidebar with unread badges + inline folder CRUD

  • AI assistant: natural language email commands (Ollama, OpenAI, Anthropic, Google)

  • AI Improve: rewrite email body with style/length/mood controls

  • AI Assist: describe a service in plain language, LLM fills the config form

  • Auto-Respond: rule-based + AI-powered auto-reply with spam detection and spoof mode

  • Bulk Send: paste email lists with rate limiting and anti-spam safeguards

  • Dual transport: stdio (Claude Desktop) + HTTP streamable (web)

  • Draft management: save/compose/send from the webapp

  • Toast notifications: live feedback for all actions

  • Prompt injection defense: two-layer sanitization (Unicode stripping + safety boundary wrapping)

  • Mail Lab: throwaway SMTP server for testing with AI-generated messages

  • Mail Watcher: background IMAP polling with webhook notifications for robofang/fleet-agent integration

  • Contact import: CSV, vCard, Google People API, Microsoft Graph API + curated lists (US Congress, EU, Austria)

  • Creative Workflows: 7 AI letter presets with ASCII art and SVG card output

  • Folder management: create, rename, delete IMAP folders from the webapp

  • Quick Setup: one-click Gmail/Outlook/Yahoo/iCloud/ProtonMail/Zoho/GMX/Fastmail with email+password

Web Dashboard

Page

Route

Purpose

Dashboard

/

KPI cards, recent activity, service health

Inbox

/inbox

Read, filter, delete, auto-refresh

Email Detail

/email

Full email with HTML body, reply/delete

Compose

/compose

Send with drafts, HTML toggle, AI Improve, AI subject, Expander, Bulk Send

Search

/search

Full-text IMAP search

AI Chat

/chat

Natural language email assistant with creative workflows

Mail Lab

/lab

Throwaway SMTP server, AI message generator, mail watcher

Contacts

/contacts

Import CSV/vCard/Google/Office 365, search, groups, curated lists

Auto-Reply

/auto-respond

Rule-based + AI auto-reply, spam detection, spoof mode, pending approval

Services

/services

Form-based add/remove/test with AI Assist presets

Tools

/tools

Execute MCP tools from the browser

Settings

/settings

AI provider config, email credentials

Help

/help

Tabbed documentation (6 tabs)

Tools

Tool

Description

send_email

Send via any service

check_inbox

Read IMAP inbox

fetch_email_detail

Get full email with body

search_emails

IMAP full-text search

delete_email

Remove email (IMAP)

move_email

Move between folders (COPY + DELETE)

copy_email

Copy to another folder, original stays

forward_email

Forward with optional comment

mark_email_read / mark_email_unread

Toggle read status

email_connector

Fleet events: aiwatcher ingest / robofang hook / status

email_status

Test connectivity

list_services

List configured services

configure_service / remove_service

Manage services

quick_setup

One-click Gmail/Outlook/Yahoo/iCloud

list_folders / create_folder / delete_folder / rename_folder

IMAP folder CRUD

email_help

Usage help and documentation

mailing_lists_catalog

List newsletter presets

mailing_list_latest

Fetch from a preset

suggest_email_subject

AI subject line (sampling)

email_agentic_assist

Multi-step email plan

add_contact / search_contacts

Contact management

start_watcher / stop_watcher / watcher_status

Background IMAP polling

run_workflow

Creative email generation

add_auto_rule / list_auto_rules / delete_auto_rule

Auto-respond rules

list_pending_replies / approve_reply / auto_respond_now

Pending reply management

Ports

Service

Port

Web dashboard frontend

10812

Backend API + MCP HTTP

10813

Native Desktop App (Tauri 2.0)

A standalone Windows desktop app is available, bundling the webapp + Python backend into a single installer (~15 MB).

# Build everything in one command:
just build-native

# Installer lands at:
# native/target/release/bundle/nsis/Email MCP_0.1.0_x64-setup.exe

Requires Rust, Node.js 20+, and Visual Studio Build Tools (for C++ compilation). The backend is compiled via PyInstaller and bundled as a Tauri sidecar -- no Python runtime needed.

Development

# Install all dependencies
uv sync --extra test --extra dev

# Start the web dashboard
.\start.ps1

# Run all backend tests
.venv\Scripts\pytest.exe tests -q

# Run Playwright e2e tests
cd webapp && npx playwright test && cd ..

# Full test suite
.venv\Scripts\pytest.exe tests -q && cd webapp && npx playwright test && cd ..

# Build MCPB package
uv run python build_mcpb.py

# Lint
uv run ruff check src

See docs/quickstart.md for full setup guide.

License

MIT

Available Tools

10 tools
check_inboxA

Check inbox via specified email service.

Retrieves emails from the specified service and folder. Supports IMAP-based services, local testing services with web APIs, and service-specific inbox checking.

Args: service: Email service to check. Options: - "default": Default IMAP service (from env vars) - "mailhog": Local MailHog testing service - "mailpit": Local Mailpit testing service - Custom service names that support inbox checking folder: Mail folder name to check. Default: "INBOX". Common folders: - "INBOX": Main inbox folder - "Sent": Sent items folder - "Drafts": Draft messages folder - "Trash": Deleted messages folder Folder names are case-sensitive and provider-specific. limit: Maximum number of emails to return. Default: 10. unread_only: If True, only returns unread emails. Default: False. from_contains: Optional case-insensitive substring filter on From (IMAP scans recent mail). subject_contains: Optional case-insensitive substring filter on Subject.

Returns: Dictionary with service-specific results: { "success": bool, # True if inbox check succeeded "emails": [ # List of email dictionaries { "id": str, # Message ID "subject": str, # Email subject "from": str, # Sender address "date": str, # Email date "read": bool # Read status } ], "count": int, # Number of emails returned "service": str, # Service used "folder": str, # Folder checked "error": str # Error message if success is False }

Examples: # Check default IMAP inbox check_inbox() # Returns: {"success": True, "emails": [...], "count": 10, "service": "default"}

# Check MailHog testing inbox
check_inbox(service="mailhog", limit=20)
# Returns emails from local testing service

# Check unread emails only
check_inbox(unread_only=True, limit=5)

Notes: - Not all services support inbox checking (API/webhook services typically don't) - Local testing services provide web UIs for viewing emails - IMAP services support standard folder names - Results are sorted with most recent first

Inputs: service, folder, limit, unread_only, +2 more. Returns: object

configure_serviceA

Configure a new email service dynamically.

Adds a new email service configuration at runtime. The service will be available for sending emails and inbox checking immediately.

Args: name: Unique name for the service (e.g., "my-sendgrid", "dev-mailhog") type: Service type - "smtp", "api", "local", or "webhook" config: Service-specific configuration dictionary enabled: Whether the service should be enabled (default: True)

Returns: Dictionary with configuration result: { "success": bool, "service": str, # Service name "type": str, # Service type "message": str # Success/error message }

Examples: # Configure SendGrid API service configure_service( name="my-sendgrid", type="api", config={ "api_key": "your-sendgrid-key", "api_url": "https://api.sendgrid.com/v3/mail/send", "from_email": "noreply@yourdomain.com", "service_type": "sendgrid" } )

# Configure local MailHog for testing
configure_service(
    name="local-testing",
    type="local",
    config={
        "smtp_server": "localhost",
        "smtp_port": 1025,
        "http_url": "http://localhost:8025",
        "service_type": "mailhog"
    }
)

Notes: - Service names must be unique - Configuration is stored in memory (not persisted) - Use list_services() to see available services

Inputs: name (required), type (required), config (required), enabled. Returns: object

email_agentic_assistB

Plan a short multi-step email workflow using sampling (agentic assist).

Uses the host LLM via sampling when available; optional Anthropic fallback if configured.

Inputs: goal (required). Returns: object

email_helpA

Get help and usage information for email MCP tools and services.

Returns comprehensive help information including available tools, supported services, usage examples, configuration requirements, and common use cases.

Returns: Dictionary with service and tool information: { "server": str, # Server name "version": str, # Server version "description": str, # Server description "supported_services": { # Available service types "smtp": str, # Description of SMTP services "api": str, # Description of API services "local": str, # Description of local services "webhook": str # Description of webhook services }, "tools": [...], # List of available tools "examples": [...], # Usage examples "notes": [...] # Important notes and tips }

Examples: # Get comprehensive help email_help() # Returns full documentation for all services and tools

Notes: - Use list_services() to see currently configured services - Use email_status() to test service connectivity - Use configure_service() to add new services dynamically

Inputs: no named parameters. Returns: object

email_statusA

Get email service status and test connectivity.

Tests connectivity for specified service or all configured services. Verifies that credentials are correct and services are reachable.

Args: service: Specific service to test, or None for all services.

Returns: Dictionary with service status information: { "server": str, # Server name "version": str, # Server version "services": { # Service-specific status "service_name": { "configured": bool, "connected": bool, "error": str, # Error message if connection failed "type": str # Service type (smtp, api, local, webhook) } }, "total_services": int, "configured_services": int, "connected_services": int }

Examples: # Check all services email_status() # Returns status for all configured services

# Check specific service
email_status(service="sendgrid")
# Returns status only for SendGrid service

Notes: - Tests actual connectivity, not just configuration presence - Connection tests are quick (timeout after 5-10 seconds) - API keys and passwords are not exposed in results

Inputs: service. Returns: object

list_servicesA

List all configured email services.

Returns information about all available email services, their types, and configuration status.

Returns: Dictionary with service information: { "services": { "service_name": { "type": str, # Service type "enabled": bool, # Whether service is enabled "configured": bool, # Whether properly configured "description": str # Human-readable description } }, "count": int, # Total number of services "enabled_count": int, # Number of enabled services "types": [str] # List of available service types }

Examples: # List all services list_services() # Returns: { # "services": { # "default": {"type": "smtp", "enabled": true, "configured": true, "description": "Default SMTP/IMAP service"}, # "sendgrid": {"type": "api", "enabled": true, "configured": true, "description": "SendGrid transactional email"} # }, # "count": 2, # "enabled_count": 2, # "types": ["smtp", "api", "local", "webhook"] # }

Notes: - Shows both automatically configured and manually added services - Configuration status indicates if required credentials are available - Use email_status() to test actual connectivity

Inputs: no named parameters. Returns: object

mailing_list_latestA

MAILING_LIST_LATEST — Fetch newest messages for a preset id (see mailing_lists_catalog).

Loads folder/service/filters from EMAIL_MCP_MAILING_LISTS. Typical use: newsletter drops in a dedicated IMAP folder (Alpha Signal, etc.). Optional limit/unread_only override entry defaults.

Args: list_id: Preset id from catalog (e.g. alphasignal). limit: Override max messages (default: from preset, usually 5). unread_only: Override UNSEEN-only (default: from preset, usually True for newest drop).

Returns: Same shape as check_inbox plus list_id and preset fields.

Inputs: list_id (required), limit, unread_only. Returns: object

mailing_lists_catalogA

MAILING_LISTS_CATALOG — List named mailing-list presets from EMAIL_MCP_MAILING_LISTS (JSON).

Configure labels/folders once (e.g. Gmail filter → IMAP folder), then use mailing_list_latest(id).

Returns: success, entries[] with id, service, folder, limit, unread_only, from_contains, subject_contains; or error if unset/invalid JSON.

Inputs: no named parameters. Returns: object

send_emailA

Send an email via specified email service.

Sends an email using the specified email service. Supports SMTP, API-based services, local testing services, and webhook integrations. Automatically detects service capabilities and uses the appropriate sending method.

Args: to: Recipient email address(es). Can be: - Single address: "user@example.com" - Comma-separated: "user1@example.com, user2@example.com" - List: ["user1@example.com", "user2@example.com"] subject: Email subject line. Required. body: Plain text email body. Required. This serves as the fallback for email clients that don't support HTML. service: Email service to use. Options: - "default": Default SMTP/IMAP service (from env vars) - "sendgrid": SendGrid transactional email - "mailgun": Mailgun transactional email - "resend": Resend transactional email - "mailhog": Local MailHog testing service - "slack": Send to Slack webhook - "discord": Send to Discord webhook - Custom service names configured via EMAIL_SERVICES html: Optional HTML email body. If provided, the email will be sent as multipart/alternative with both text and HTML versions. Example: "TitleContent" cc: Optional CC (carbon copy) recipients. Same format as 'to'. bcc: Optional BCC (blind carbon copy) recipients. Same format as 'to'.

Returns: Dictionary with service-specific results: { "success": bool, # True if email sent successfully "status": str, # "sent" on success "service": str, # Service used "to": str, # Recipient address(es) "subject": str, # Email subject "error": str # Error message if success is False }

Examples: # Send via default SMTP service send_email( to="user@example.com", subject="Hello", body="This is a test email" )

# Send via SendGrid
send_email(
    to="user@example.com",
    subject="Welcome",
    body="Welcome to our service",
    service="sendgrid",
    html="<h1>Welcome!</h1><p>Thanks for joining.</p>"
)

# Send to Slack webhook
send_email(
    to="general",
    subject="Alert",
    body="System alert message",
    service="slack"
)

Notes: - Service availability depends on configuration - API services may have different rate limits and features - Local testing services don't send real emails - Webhook services convert emails to chat messages

Inputs: to (required), subject (required), body (required), service, +3 more. Returns: object

suggest_email_subjectA

Suggest 1–3 concise email subject lines for the given body (uses MCP sampling when available).

Inputs: body (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have distinct purposes (send, receive, configure, status, help), but mailing_list_latest overlaps slightly with check_inbox as a specialized variant. Descriptions help differentiate.

    Naming Consistency3/5

    Uses snake_case consistently, but mixes verb-first (check_inbox, list_services) with noun-first (email_help, email_status) patterns. Also 'mailing_' prefix vs 'email_' adds inconsistency.

    Tool Count5/5

    10 tools cover essential email operations plus extras (help, subject suggestions, mailing list presets) without being overwhelming.

    Completeness3/5

    Core send/receive and service management are covered, but lacks email deletion, folder movement, and attachment support, which are common email tasks.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive MCP server for unified email management that supports both Gmail and IMAP accounts via a single interface. It enables users to search across multiple accounts, list, read, send, and archive emails with integrated health monitoring and secure authentication.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provider-agnostic email MCP server that connects any IMAP mailbox to AI assistants, enabling email management through natural language.
      8
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Cross-platform MCP server and CLI for email operations, including send, read, search, and contact management, compatible with Gmail, Outlook, Yahoo, and any IMAP/SMTP providers.
      29 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.
      MIT