martinzarfl/mail-mcp

Mail MCP Server

A Model Context Protocol (MCP) server for SMTP and IMAP-based email handling. This server enables AI assistants to send and read emails, manage mailboxes, and handle email configurations securely.

Features

Sending Emails (SMTP)

• Send Emails: Send emails with HTML/plain text content, attachments, and CC/BCC support
• Connection Verification: Test SMTP connection and authentication
• Configuration Testing: Test custom SMTP configurations without modifying server settings

Reading Emails (IMAP)

• Fetch Emails: Retrieve emails from any mailbox with filtering options
• Search Emails: Simple search by subject, sender, or content
• Advanced Search: Complex queries with multiple criteria (sender, recipient, date range, size, flags)
• List Mailboxes: Browse all available folders/mailboxes
• Mark Emails: Mark emails as read/unread or flagged/unflagged

Email Organization

• Create/Delete Mailboxes: Manage folder structure
• Move Messages: Organize emails between folders
• Copy Messages: Duplicate emails to multiple folders
• Save Drafts: Store draft emails for later editing

Advanced Features

• Thread View: Get entire conversation threads with chronological ordering
• Download Attachments: Retrieve specific attachments with base64 encoding
• Message Relationships: Track reply chains via Message-ID, In-Reply-To, and References headers

Security

• Secure: All credentials managed via environment variables
• TLS Support: Encrypted connections for both SMTP and IMAP

Installation

npm install
npm run build

Configuration

Required Environment Variables

# SMTP Configuration (for sending emails)
export SMTP_HOST="smtp.gmail.com"          # SMTP server hostname
export SMTP_PORT="587"                      # SMTP server port (587 or 465)
export SMTP_USER="your-email@gmail.com"    # SMTP username
export SMTP_PASS="your-app-password"       # SMTP password
export SMTP_FROM="your-email@gmail.com"    # (Optional) Default sender address
export SMTP_SECURE="false"                 # (Optional) Use TLS (true for port 465)

Optional IMAP Configuration (for reading emails)

If not provided, IMAP settings default to SMTP values:

export IMAP_HOST="imap.gmail.com"          # IMAP server (defaults to SMTP_HOST)
export IMAP_PORT="993"                      # IMAP port (default: 993)
export IMAP_USER="your-email@gmail.com"    # IMAP username (defaults to SMTP_USER)
export IMAP_PASS="your-app-password"       # IMAP password (defaults to SMTP_PASS)
export IMAP_TLS="true"                     # Use TLS (default: true)

Usage

Running the Server

Stdio Transport (Default)

For use with Claude Desktop or other stdio-based clients:

# Without .env
npm run dev

# With .env file
npm run dev:env

SSE Transport (HTTP/Server-Sent Events)

For web-based clients or remote connections:

# Start SSE server on port 3000
TRANSPORT=sse npm run dev:sse:env

# Or custom port
TRANSPORT=sse PORT=8080 npm run dev:sse:env

The server will be available at:

• MCP endpoint: http://localhost:3000/mcp
• SSE endpoint: http://localhost:3000/sse

Environment Variables for SSE:

• TRANSPORT=sse - Enable SSE transport
• PORT=3000 - HTTP server port (default: 3000)
• SSE_PATH=/sse - SSE endpoint path (default: /sse)

Using with Claude Desktop (Stdio)

Add to your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["-y", "martinzarfl/mail-mcp"],
      "env": {
        "SMTP_HOST": "smtp.provider.com",
        "SMTP_PORT": "587",
        "SMTP_USER": "your-email@provider.com",
        "SMTP_PASS": "your-mail-password",
        "SMTP_FROM": "your-email@provider.com",
        "IMAP_HOST": "imap.provider.com",
        "IMAP_PORT": "993",
        "IMAP_USER": "your-email@provider.com",
        "IMAP_PASS": "your-mail-password"
      }
    }
  }
}

Available Tools

SMTP Tools (Sending Emails)

send_email

Send an email via SMTP.

Parameters:

• to (required): Recipient email address
• subject (required): Email subject line
• text (optional): Plain text email body
• html (optional): HTML email body
• from (optional): Sender email address (uses SMTP_FROM if not provided)
• cc (optional): CC recipient email address
• bcc (optional): BCC recipient email address
• attachments (optional): Array of attachments with filename, content, and encoding (base64 or utf-8)

Example:

{
  "to": "recipient@example.com",
  "subject": "Hello from MCP",
  "text": "This is a test email",
  "html": "<h1>This is a test email</h1>"
}

verify_connection

Verify the SMTP connection and authentication using configured credentials.

Parameters: None

test_smtp_config

Test SMTP configuration with custom credentials without modifying the server configuration.

Parameters:

• host (required): SMTP server hostname
• port (required): SMTP server port
• user (required): SMTP authentication username
• password (required): SMTP authentication password
• secure (optional): Use TLS (default: true for port 465)

get_smtp_info

Get information about the current SMTP configuration (without revealing credentials).

Parameters: None

IMAP Tools (Reading Emails)

list_mailboxes

List all available mailboxes/folders in the IMAP account.

Parameters: None

Example Response:

{
  "success": true,
  "mailboxes": [
    {"name": "INBOX", "delimiter": "/", "children": 0},
    {"name": "Sent", "delimiter": "/", "children": 0},
    {"name": "Drafts", "delimiter": "/", "children": 0}
  ],
  "count": 3
}

fetch_emails

Fetch emails from a specific mailbox with optional filters.

Parameters:

• mailbox (optional): Mailbox name (default: "INBOX")
• limit (optional): Maximum emails to fetch, 1-100 (default: 10)
• unseen (optional): Only fetch unread emails (default: false)
• since (optional): Only fetch emails since date (ISO 8601 format)

Example:

{
  "mailbox": "INBOX",
  "limit": 5,
  "unseen": true
}

search_emails

Search for emails in a mailbox by subject, sender, or content.

Parameters:

• mailbox (optional): Mailbox name (default: "INBOX")
• query (required): Search query string
• limit (optional): Maximum results, 1-100 (default: 10)

Example:

{
  "query": "meeting",
  "limit": 10
}

mark_email

Mark an email with a specific flag.

Parameters:

• mailbox (optional): Mailbox name (default: "INBOX")
• uid (required): Email UID to mark
• flag (required): Flag to set ("read", "unread", "flagged", "unflagged")

Example:

{
  "uid": 123,
  "flag": "read"
}

Advanced IMAP Tools

create_mailbox

Create a new mailbox/folder in your email account.

Parameters:

• name (required): Name of the mailbox to create

Example:

{
  "name": "Projects"
}

delete_mailbox

Delete a mailbox/folder from your email account.

Parameters:

• name (required): Name of the mailbox to delete

Example:

{
  "name": "OldFolder"
}

move_message

Move an email from one mailbox to another.

Parameters:

• sourceMailbox (optional): Source mailbox (default: "INBOX")
• targetMailbox (required): Target mailbox name
• uid (required): Email UID to move

Example:

{
  "sourceMailbox": "INBOX",
  "targetMailbox": "Archive",
  "uid": 123
}

copy_message

Copy an email from one mailbox to another.

Parameters:

• sourceMailbox (optional): Source mailbox (default: "INBOX")
• targetMailbox (required): Target mailbox name
• uid (required): Email UID to copy

Example:

{
  "targetMailbox": "Important",
  "uid": 456
}

advanced_search

Search emails with multiple criteria including sender, recipient, subject, body, date range, size, and flags.

Parameters:

• mailbox (optional): Mailbox name (default: "INBOX")
• criteria (required): Search criteria object with fields:
  • from: Search by sender
  • to: Search by recipient
  • subject: Search by subject text
  • body: Search by body text
  • since: Date filter (ISO 8601)
  • before: Date filter (ISO 8601)
  • unseen: Only unread emails (boolean)
  • flagged: Only flagged emails (boolean)
  • larger: Minimum size in bytes
  • smaller: Maximum size in bytes
• limit (optional): Maximum results, 1-100 (default: 10)

Example:

{
  "criteria": {
    "from": "boss@company.com",
    "since": "2025-01-01",
    "unseen": true
  },
  "limit": 20
}

save_draft

Save an email as a draft in the Drafts folder without sending it.

Parameters:

• to (required): Recipient email address
• subject (required): Email subject
• text (optional): Plain text body
• html (optional): HTML body
• from (optional): Sender address
• cc (optional): CC recipient
• bcc (optional): BCC recipient

Example:

{
  "to": "colleague@company.com",
  "subject": "Draft: Project Update",
  "text": "This is a draft email..."
}

get_thread

Get all emails in a conversation thread based on a message ID. Returns emails sorted chronologically with reply relationships.

Parameters:

• mailbox (optional): Mailbox name (default: "INBOX")
• messageId (required): Message ID to find thread for

Example:

{
  "messageId": "<abc123@mail.example.com>"
}

Response includes:

• messageId: Unique message identifier
• inReplyTo: Parent message ID
• references: All related message IDs
• Full email content sorted by date

download_attachment

Download a specific attachment from an email. Returns the attachment content as base64-encoded data.

Parameters:

• mailbox (optional): Mailbox name (default: "INBOX")
• uid (required): Email UID
• attachmentIndex (required): Attachment index (0-based)

Example:

{
  "uid": 789,
  "attachmentIndex": 0
}

Response:

{
  "success": true,
  "filename": "report.pdf",
  "contentType": "application/pdf",
  "size": 102400,
  "content": "JVBERi0xLjQKJeLjz9MKM...",
  "encoding": "base64"
}

Development

# Build the project
npm run build

# Watch for changes
npm run watch

# Run in development mode
npm run dev

Security Notes

• Never commit credentials to version control
• Use environment variables for sensitive data
• Consider using App Passwords instead of regular passwords
• Use TLS/SSL for secure connections (port 465 or STARTTLS on 587)

Common Email Providers

Notes:

• Port 587: Use with STARTTLS (set SMTP_SECURE="false")
• Port 465: Use with SSL/TLS (set SMTP_SECURE="true")
• Port 993: Standard IMAP over SSL/TLS

License

MIT