Mail Organizer

You can manage and organize your email with a unified MCP server that provides mailbox operations, powerful search, email actions, flag management, and sending capabilities. It supports safe workflows with preview options and scalable batch handling so you can automate routine tasks without risking data loss.

How to use

You interact with the MCP Mail Organizer through an MCP client that can connect via standard input/output (stdio). Start the server locally or connect to a remote MCP endpoint, then use the available endpoints to manage mailboxes, search and retrieve emails, perform operations like moving or deleting messages, set flags, and send new emails. Use the client to run specific tools for mailbox management, search, and sending, and enable preview mode for any destructive actions to review changes before they apply.

How to install

Prerequisites: you need Node.js and npm installed on your system. You also need access to an email account to configure IMAP/SMTP credentials.

# Global installation (recommended)
npm install -g mcp-mail-organizer

# Local installation (clone and build)
git clone https://github.com/neomody77/mcp-mail-organizer.git
cd mcp-mail-organizer
npm install
npm run build

# Create environment file for credentials
cp .env.example .mail.env

# Configure your email credentials in .mail.env
# Example values (replace with real credentials)
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

Configuration and running modes

You can run the server in stdio mode using either the global CLI or a local Node.js invocation. The global approach uses the installed command directly, while the local approach runs the built distribution.

# Global stdio run (CLI installed globally)
mcp-mail-organizer --env-file .mail.env

# Local stdio run (from repository after build)
node dist/index.js --env-file .mail.env

Practical usage patterns

• Manage mailboxes: list existing folders and create new ones as needed.
• Search emails: filter by from, to, subject, date ranges, and flags to quickly locate messages.
• Email operations: get details for a message, move messages to a different mailbox, or delete messages with safety previews.
• Flags: mark emails as read or unread and apply or remove custom flags for organization.
• Sending: compose and send emails with text or HTML content and optional attachments.

Security and safety features

Preview mode is available for destructive actions such as delete and move, so you can review exactly what will happen before changes are applied. For large tasks, break them into smaller batches (for example, 200 messages per batch) to reduce the risk of errors.

Troubleshooting

If you run into issues, check that all required environment variables are provided and correctly loaded from the environment file. The server performs connection tests to validate SMTP/IMAP access and provides detailed logs to help identify where problems occur. If an operation fails due to server limitations (like MOVE not supported), the system can automatically fall back to COPY+DELETE.

Notes and tips

All credentials are stored in environment files and are not embedded in configurations. Use distinct environment files per deployment to keep credentials isolated.

Example workflows

Search for unread emails in the last 7 days and limit results to 10, then inspect the results before taking any action.

Available tools

list_mailboxes

List all available mailboxes or folders so you know where to store or move messages.

create_mailbox

Create a new mailbox or folder to organize your messages.

search_emails

Search emails using criteria such as from, to, subject, date ranges, and flags.

get_email

Get detailed information about a specific email, including headers and body content.

move_emails

Move one or more emails to a different mailbox.

delete_emails

Delete emails permanently with an optional preview to review changes first.

mark_seen

Mark emails as read or unread.

add_flags

Add custom flags to emails for better organization.

remove_flags

Remove flags from emails on selected emails.

send_mail

Send an email with text/HTML content and optional attachments.