imap-smtp-email-mcp

MCP (Model Context Protocol) server for email — read and send emails from your AI assistant. Works with Gmail, Outlook, QQ Mail, 163.com, 126.com, 188.com, and any standard IMAP/SMTP server.

Features

• Read emails — check inbox, search with filters, fetch full content (text + HTML), download attachments
• Send emails — plain text, HTML, attachments, CC, BCC, reply-to threading
• Manage inbox — mark read/unread, list mailboxes/folders
• Zero config bloat — 6 environment variables, one account, no multi-tenant noise
• Runs via npx — no install required for MCP clients

Quick Start

Add to your MCP client configuration (e.g. Claude Desktop, VS Code, etc.):

{
  "mcpServers": {
    "imap-smtp-email": {
      "command": "npx",
      "args": ["-y", "imap-smtp-email-mcp"],
      "env": {
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_PORT": "993",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "465",
        "EMAIL_USER": "[email protected]",
        "EMAIL_PASS": "your-app-password"
      }
    }
  }
}

Note: Most email providers require an app-specific password rather than your regular login password. See Gmail App Passwords, Outlook App Passwords, etc.

Tools

IMAP (Receive)

| Tool | Description | |------|-------------| | imap_check | Check for new/unread emails | | imap_search | Search emails by unseen/seen, sender, subject, date range | | imap_fetch | Fetch full email content (text, HTML, headers, attachment metadata) | | imap_download | Download email attachments to disk | | imap_mark_read | Mark emails as read by UID | | imap_mark_unread | Mark emails as unread by UID | | imap_list_mailboxes | List all mailboxes/folders | | imap_list_accounts | List configured email accounts |

SMTP (Send)

| Tool | Description | |------|-------------| | smtp_send | Send email with plain text, HTML, attachments, CC, BCC, reply headers | | smtp_test | Test SMTP configuration by sending a test email to yourself | | smtp_list_accounts | List configured SMTP accounts |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | IMAP_HOST | Yes | — | IMAP server hostname | | IMAP_PORT | No | 993 | IMAP server port | | SMTP_HOST | Yes | — | SMTP server hostname | | SMTP_PORT | No | 465 | SMTP server port | | EMAIL_USER | Yes | — | Email address / login username | | EMAIL_PASS | Yes | — | Password or app-specific password |

Common Provider Settings

| Provider | IMAP Host | IMAP Port | SMTP Host | SMTP Port | |----------|-----------|-----------|-----------|-----------| | Gmail | imap.gmail.com | 993 | smtp.gmail.com | 465 | | Outlook | outlook.office365.com | 993 | smtp.office365.com | 587 | | QQ Mail | imap.qq.com | 993 | smtp.qq.com | 465 | | 163.com | imap.163.com | 993 | smtp.163.com | 465 | | 126.com | imap.126.com | 993 | smtp.126.com | 465 | | 188.com | imap.188.com | 993 | smtp.188.com | 465 |

Manual Testing

# Start the MCP server directly
IMAP_HOST=imap.gmail.com \
SMTP_HOST=smtp.gmail.com \
[email protected] \
EMAIL_PASS=your-app-password \
npx imap-smtp-email-mcp

# Or with MCP Inspector
npx @anthropic-ai/mcp-inspector \
  -e IMAP_HOST=imap.gmail.com \
  -e SMTP_HOST=smtp.gmail.com \
  -e [email protected] \
  -e EMAIL_PASS=your-app-password \
  npx imap-smtp-email-mcp

Programmatic Usage

The IMAP/SMTP client library is available as a standalone import for use in your own Node.js projects:

import { ImapClient, SmtpClient } from 'imap-smtp-email-mcp';

const imap = new ImapClient({
  default: {
    user: '[email protected]',
    password: 'your_password',
    host: 'imap.gmail.com',
    port: 993,
    tls: true,
    defaultMailbox: 'INBOX',
  },
});

const emails = await imap.checkEmails({ limit: 5 });

const smtp = new SmtpClient({
  default: {
    host: 'smtp.gmail.com',
    port: 465,
    secure: true,
    user: '[email protected]',
    password: 'your_password',
    defaultFrom: '[email protected]',
  },
});

await smtp.sendEmail({
  to: '[email protected]',
  subject: 'Hello',
  body: 'Hello from imap-smtp-email-mcp!',
});

Requirements

• Node.js >= 18
• An email account with IMAP/SMTP access enabled

License

MIT