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

1. Clone the repository:

git clone https://github.com/neomody77/mcp-mail-organizer.git
cd mcp-mail-organizer
npm install
npm run build

2. Create environment file:

cp .env.example .mail.env

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

{
  "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 .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

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

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

License

MIT