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)
npm install -g mcp-mail-organizer
Local Installation
- Clone the repository:
git clone https://github.com/neomody77/mcp-mail-organizer.git
cd mcp-mail-organizer
npm install
npm run build
- Create environment file:
cp .env.example .mail.env
- Configure your email credentials in
.mail.env:
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your.email@gmail.com
SMTP_PASS=your-app-specific-password
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
IMAP_USER=your.email@gmail.com
IMAP_PASS=your-app-specific-password
Usage with Claude Code
Global Installation Usage
Add to your Claude Code .mcp.json file:
{
"mcpServers": {
"mail-organizer": {
"command": "mcp-mail-organizer",
"args": ["--env-file", ".mail.env"],
"cwd": ".",
"env": {}
}
}
}
Local Installation Usage
{
"mcpServers": {
"mail-organizer": {
"command": "node",
"args": ["./mcp-mail-organizer/dist/index.js", "--env-file", ".mail.env"],
"cwd": ".",
"env": {}
}
}
}
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
{
"name": "search_emails",
"arguments": {
"unreadOnly": true,
"sinceDays": 7,
"limit": 10
}
}
Move emails to folder
{
"name": "move_emails",
"arguments": {
"uids": [123, 456],
"destination": "Archive/2025"
}
}
Send email
{
"name": "send_mail",
"arguments": {
"to": "recipient@example.com",
"subject": "Test Subject",
"text": "Hello from MCP Mail Organizer!"
}
}
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
.envfiles, 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
npm run dev # Watch mode for development
npm run build # Build TypeScript
npm start # Start production server
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Repository
License
MIT