mcp-email

A minimal MCP server for reading, searching, managing, and sending email over IMAP and SMTP. Version 0.1 targets Gmail, while connection settings remain configurable through environment variables.

Features

• Connect to and health-check an IMAP account
• List folders and recent inbox messages
• Read plain-text and HTML email bodies
• Search by unread status, subject, sender, and date
• Send plain-text or HTML email with optional CC and BCC
• Mark messages read or unread and permanently delete messages
• List attachment filenames
• Return a cleaned email body as a basic summary

Setup

Python 3.12 or newer is required.

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Copy .env.example to .env and fill in your account details. For Gmail, enable IMAP and use a Google App Password instead of your account password. Never commit .env.

EMAIL_PROVIDER=gmail
EMAIL_ADDRESS=example@gmail.com
EMAIL_SECRET=your-google-app-password
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465

Run

python server.py

Example MCP client configuration:

{
  "mcpServers": {
    "email": {
      "command": "python",
      "args": [
        "C:/Users/your-user/Documents/GitHub/mcp-email/server.py"
      ]
    }
  }
}

Tools

• connect()
• health()
• list_folders()
• latest_emails(limit=5)
• read_email(message_id)
• search_emails(unread=False, subject=None, sender=None, since=None, before=None, limit=50)
• send_email(to, subject, body, cc=None, bcc=None, html=False)
• mark_read(message_id)
• mark_unread(message_id)
• delete_email(message_id)
• list_attachments(message_id)
• summarize_email(message_id)

delete_email expunges the selected message immediately and cannot be undone.