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)

Related MCP server: Gmail MCP Server

Installation

Global Installation (Recommended)

Local Installation

1. Clone the repository:

2. Create environment file:

3. 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/folders

• create_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 mailbox

• delete_emails: Delete emails permanently (with preview mode)

• mark_seen: Mark emails as read or unread

• add_flags: Add flags to emails

• remove_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

1. Enable 2-factor authentication

2. Generate an app-specific password

3. Use IMAP settings:

   • IMAP: imap.gmail.com:993 (SSL)

   • SMTP: smtp.gmail.com:587 (STARTTLS)

Outlook/Hotmail

1. Enable IMAP in Outlook settings

2. Use IMAP settings:

   • IMAP: outlook.office365.com:993 (SSL)

   • SMTP: smtp-mail.outlook.com:587 (STARTTLS)

139.com (China Mobile)

1. Enable IMAP/SMTP in webmail settings

2. Login to webmail.139.com → Settings → Enable IMAP/SMTP

3. Use IMAP settings:

   • IMAP: imap.139.com:993 (SSL)

   • SMTP: smtp.139.com:587 (STARTTLS)

QQ Mail

1. Generate authorization code in QQ Mail settings

2. 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:

1. Environment Variables: The server validates all required variables on startup

2. Connection Testing: Automatically tests SMTP/IMAP connections

3. Debug Output: Detailed logging shows exactly where failures occur

4. Preview Mode: Destructive operations show preview by default

Development

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

• GitHub: https://github.com/neomody77/mcp-mail-organizer

• NPM: mcp-mail-organizer

License

MIT