Skip to main content
Glama

MCP Mail Organizer

by neomody77

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

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
  1. Create environment file:
cp .env.example .mail.env
  1. 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

License

MIT

-
security - not tested
F
license - not found
-
quality - not tested

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.

  1. Features
    1. Installation
      1. Global Installation (Recommended)
      2. Local Installation
    2. Usage with Claude Code
      1. Global Installation Usage
      2. Local Installation Usage
    3. Available Tools
      1. Mailbox Management
      2. Email Search & Retrieval
      3. Email Operations
      4. Email Sending
    4. Example Usage
      1. Search for unread emails
      2. Move emails to folder
      3. Send email
    5. Safety Features
      1. Email Provider Setup
        1. Gmail
        2. Outlook/Hotmail
        3. 139.com (China Mobile)
        4. QQ Mail
      2. Troubleshooting
        1. Development
          1. Contributing
            1. Repository
              1. License

                Related MCP Servers

                • -
                  security
                  A
                  license
                  -
                  quality
                  Integrates 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 -
                  2
                  Python
                  GPL 3.0
                • -
                  security
                  A
                  license
                  -
                  quality
                  Enables 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 -
                  13
                  Python
                  Apache 2.0
                  • Apple
                  • Linux
                • A
                  security
                  A
                  license
                  A
                  quality
                  Provides IMAP and SMTP capabilities, enabling developers to manage email services with seamless integration and automated workflows.
                  Last updated -
                  4
                  64
                  Python
                  BSD 3-Clause
                  • Apple
                  • Linux
                • -
                  security
                  A
                  license
                  -
                  quality
                  Provides comprehensive Gmail integration with LLM processing capabilities, allowing users to read, search, filter emails and handle attachments through the Model Context Protocol.
                  Last updated -
                  11
                  1
                  TypeScript
                  MIT License

                View all related MCP servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/neomody77/mcp-mail-organizer'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server