Provides comprehensive email management capabilities including searching, organizing, sending emails, managing mailboxes and flags through Gmail's IMAP/SMTP protocols
MCP Mail Organizer
A Model Context Protocol (MCP) server that provides unified mail operations with atomic tools for organizing and managing your email efficiently.
Features
- Mailbox Management: List, create mailboxes/folders
- Email Search: Search emails with multiple criteria (from, to, subject, date ranges, flags, etc.)
- Email Operations: Get detailed email information, move emails, delete emails
- Flag Management: Mark emails as read/unread, add/remove custom flags
- Email Sending: Send emails with text/HTML content and attachments
- Safety: Preview mode for destructive operations (delete, move)
Installation
Global Installation (Recommended)
Local Installation
- Clone the repository:
- Create environment file:
- Configure your email credentials in
.mail.env
:
Usage with Claude Code
Global Installation Usage
Add to your Claude Code .mcp.json
file:
Local Installation Usage
Available Tools
Mailbox Management
list_mailboxes
: List all available mailboxes/folderscreate_mailbox
: Create a new mailbox/folder
Email Search & Retrieval
search_emails
: Search emails with criteria (from, to, subject, date ranges, flags)get_email
: Get detailed information about a specific email
Email Operations
move_emails
: Move emails to another mailboxdelete_emails
: Delete emails permanently (with preview mode)mark_seen
: Mark emails as read or unreadadd_flags
: Add flags to emailsremove_flags
: Remove flags from emails
Email Sending
send_mail
: Send an email with text/HTML content and optional attachments
Example Usage
Search for unread emails
Move emails to folder
Send email
Safety Features
- Preview Mode: Destructive operations (delete, bulk move) default to preview mode
- Batch Limits: Large operations are recommended to be chunked (≤ 200 messages per batch)
- Fallback Support: Automatic fallback from MOVE to COPY+DELETE if server doesn't support MOVE
- Environment Security: All credentials stored in
.env
files, not in configuration
Email Provider Setup
Gmail
- Enable 2-factor authentication
- Generate an app-specific password
- Use IMAP settings:
- IMAP: imap.gmail.com:993 (SSL)
- SMTP: smtp.gmail.com:587 (STARTTLS)
Outlook/Hotmail
- Enable IMAP in Outlook settings
- Use IMAP settings:
- IMAP: outlook.office365.com:993 (SSL)
- SMTP: smtp-mail.outlook.com:587 (STARTTLS)
139.com (China Mobile)
- Enable IMAP/SMTP in webmail settings
- Login to webmail.139.com → Settings → Enable IMAP/SMTP
- Use IMAP settings:
- IMAP: imap.139.com:993 (SSL)
- SMTP: smtp.139.com:587 (STARTTLS)
QQ Mail
- Generate authorization code in QQ Mail settings
- Use IMAP settings:
- IMAP: imap.qq.com:993 (SSL)
- SMTP: smtp.qq.com:587 (STARTTLS)
Troubleshooting
The server includes comprehensive debug logging. If you encounter issues:
- Environment Variables: The server validates all required variables on startup
- Connection Testing: Automatically tests SMTP/IMAP connections
- Debug Output: Detailed logging shows exactly where failures occur
- Preview Mode: Destructive operations show preview by default
Development
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Repository
License
MIT
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables comprehensive email management through IMAP/SMTP protocols with tools for searching, organizing, moving, flagging, and sending emails across various email providers. Features safe preview mode for destructive operations and supports multiple email providers including Gmail, Outlook, and Chinese email services.
Related MCP Servers
- -securityAlicense-qualityIntegrates with Gmail to enable sending, reading, drafting, and managing emails via the Model Context Protocol (MCP), allowing users to interact with email tasks through automated client prompts.Last updated -2PythonGPL 3.0
- -securityAlicense-qualityEnables interaction with Gmail through the Gmail API to read, send, and manage emails. Supports multiple Gmail accounts with real-time monitoring and advanced features for email search and attachment handling.Last updated -13PythonApache 2.0
- AsecurityAlicenseAqualityProvides IMAP and SMTP capabilities, enabling developers to manage email services with seamless integration and automated workflows.Last updated -464PythonBSD 3-Clause
- -securityAlicense-qualityProvides comprehensive Gmail integration with LLM processing capabilities, allowing users to read, search, filter emails and handle attachments through the Model Context Protocol.Last updated -111TypeScriptMIT License