mcp-mail-enhanced

Enhanced Mail MCP Server 🚀

English Version • Versión en Español

🎯 What is this?

Enhanced Mail MCP Server is an advanced MCP (Model Context Protocol) server that enables MCP clients (Claude Desktop, Cursor, etc.) to perform email operations through a standardized interface with intelligent auto-configuration.

🆕 What's New in v2.0?

• ✨ Simplified Configuration: Just provide EMAIL_SERVER, EMAIL_USER, and EMAIL_PASS
• 🤖 Auto-Detection: Automatically detects SMTP/IMAP settings for popular providers
• 🏠 Local Server Support: Works with corporate and local mail servers
• 🔄 Backward Compatibility: Still supports legacy configuration
• ⚡ Enhanced Performance: Improved error handling and connection management

🚀 Quick Start

Method 1: Use with Claude Desktop / MCP Clients (Recommended)

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mail-enhanced": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mail-enhanced"
      ],
      "env": {
        "EMAIL_SERVER": "gmail.com",
        "EMAIL_USER": "[e-mail]",
        "EMAIL_PASS": "your-app-password"
      }
    }
  }
}

Method 2: Direct Execution (Testing)

You can run the server directly without installation using npx:

# Run directly with simplified config
EMAIL_SERVER=gmail.com EMAIL_USER=[e-mail] EMAIL_PASS=password npx -y mcp-mail-enhanced

Method 3: Local Development

If you have cloned the repository and want to run your local version:

# 1. Build the project
npm install && npm run build

# 2. Run with npx pointing to current directory
EMAIL_SERVER=gmail.com EMAIL_USER=[e-mail] EMAIL_PASS=password npx .

Alternative: Legacy Python Bridge

If you prefer using the Python bridge (legacy method):

{
  "mcpServers": {
    "mail-enhanced": {
      "command": "python",
      "args": ["path/to/bridging_mail_mcp.py"],
      "env": {
        "EMAIL_SERVER": "gmail.com",
        "EMAIL_USER": "[e-mail]",
        "EMAIL_PASS": "your-app-password"
      }
    }
  }
}

📋 Installation

Prerequisites

• Node.js 18+ and npm
• Python 3.11+
• Git

Install Steps

• Clone and Install

git clone https://github.com/krka/mcp-mail-enhanced.git
cd mcp-mail-enhanced
npm install

• Build the Project

npm run build

• Configure MCP Client

Add the configuration to your MCP client (Claude Desktop, Cursor, etc.) configuration file.

🏷️ Supported Email Providers

Auto-Detected Providers

• Gmail (gmail.com) - Uses Gmail's secure SMTP/IMAP
• Outlook/Hotmail (outlook.com, hotmail.com) - Microsoft Exchange
• Yahoo Mail (yahoo.com) - Yahoo's mail servers
• QQ Mail (qq.com) - Tencent's mail service
• 163 Mail (163.com) - NetEase mail
• 126 Mail (126.com) - NetEase mail

Custom/Local Servers

• Corporate mail servers (mail.company.com)
• Local development servers (localhost, 192.168.x.x)
• Any custom SMTP/IMAP server

🛠️ Features

Email Operations (Click to expand)

• Send Emails: Plain text, HTML, with attachments, bulk emails
• Receive & Query: Get folder lists, list emails, advanced search, get email details
• Manage Emails: Mark read/unread, delete emails, move emails
• Attachment Management: View attachment lists, download attachments, view attachment content
• Contact Management: Get contact lists, search contacts from email history

Advanced Features (Click to expand)

• Smart Search: Multi-folder, keyword, date range, sender/recipient complex search

• Intelligent Contact Management: Automatically extract contact info from email history with frequency analysis

• Content Range Control: View large emails in segments to avoid loading too much content

• Multiple Email Formats: Support both plain text and HTML email sending and display

• Attachment Processing: Smart attachment type recognition, support for text, image previews

• Secure & Reliable: All email operations processed locally, no third-party server forwarding

• waitForReply: Wait for a new email to arrive in a folder (long-polling).

• getAttachment: Download or view content of a specific attachment.

Management

• listFolders: List all available mail folders on the server.
• markAsRead: Mark a specific email as read.
• markAsUnread: Mark a specific email as unread.
• markMultipleAsRead: Mark multiple emails as read by UID.
• markMultipleAsUnread: Mark multiple emails as unread by UID.
• deleteEmail: Delete an email (move to Trash/Deleted).
• moveEmail: Move an email from one folder to another.
• getContacts: Extract contact list from your email history.

🔧 Development

Commands

# Development mode with auto-reload
npm run dev

# Build production version
npm run build

# Run tests
npm run test

# Start built server
npm start

Project Structure

src/
├── index.ts                    # Main entry point
├── tools/
│   ├── mail.ts                # MCP server implementation
│   ├── mail-service.ts        # Email service (SMTP/IMAP)
│   ├── email-config-detector.ts # Auto-configuration logic
│   └── process-manager.ts     # Process management
├── bridging_mail_mcp.py       # Python bridge script
└── CLAUDE.md                  # Claude Code documentation

📝 Usage Examples

This server is designed to be used naturally with LLMs. Here are some example prompts you can use:

📥 Reading Emails

Check your inbox:

"Check my inbox for new emails from the last 24 hours" Tools used: listEmails

Search for something specific:

"Search for emails from 'amazon' about 'delivery' sent this week" Tools used: searchEmails

Read a specific email:

"Read the latest email from John Doe and summarize it" Tools used: listEmails -> getEmailDetail

Check for new replies:

"Wait for a reply to the email I just sent (timeout 10 minutes)" Tools used: waitForReply

📤 Sending Emails

Send a quick email:

"Send an email to [e-mail] with subject 'Meeting' and body 'See you at 2pm'" Tools used: sendMail or sendSimpleMail

Send with attachments:

"Send the file 'report.pdf' to [e-mail]" Tools used: sendMail (with attachment)

Send to multiple people:

"Send a reminder to [e-mail] and cc [e-mail] about the deadline" Tools used: sendMail

🗂️ Managing & Organizing

Organize your inbox:

"Move all emails from '[e-mail]' to the Trash folder" Tools used: searchEmails -> moveEmail

Clean up:

"Mark all emails from yesterday as read" Tools used: listEmails -> markMultipleAsRead

Find contacts:

"Who have I emailed recently about 'project x'?" Tools used: getContacts

🤝 Contributing

We welcome contributions! Please feel free to submit issues and enhancement requests.

📄 License

ISC License - see LICENSE file for details.

🙏 Credits

This project is an enhanced fork that builds upon the original MCP mail implementation, adding significant improvements in usability and configuration management.

⭐ If this project helps you, please give it a star! (｡♥‿♥｡)