Package Exports

mcp-mail-enhanced
mcp-mail-enhanced/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (mcp-mail-enhanced) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: Direct execution with npx

# Run directly with simplified config
EMAIL_SERVER=gmail.com EMAIL_USER=tu@gmail.com EMAIL_PASS=password npx mcp-mail-enhanced

# Run from local directory (development)
EMAIL_SERVER=gmail.com EMAIL_USER=tu@gmail.com EMAIL_PASS=password npx .

Method 2: MCP Client Configuration (Recommended)

Create or update your MCP configuration file with just 3 variables:

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

Method 3: Advanced Configuration

For custom setups, use the detailed configuration:

{
  "mcpServers": {
    "mail-enhanced": {
      "command": "python",
      "args": ["path/to/bridging_mail_mcp.py"],
      "env": {
        "SMTP_HOST": "smtp.custom-server.com",
        "SMTP_PORT": "587",
        "SMTP_SECURE": "false",
        "SMTP_USER": "your.email@custom-server.com",
        "SMTP_PASS": "your-password",
        "IMAP_HOST": "imap.custom-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "IMAP_USER": "your.email@custom-server.com",
        "IMAP_PASS": "your-password",
        "DEFAULT_FROM_NAME": "Your Name",
        "DEFAULT_FROM_EMAIL": "your.email@custom-server.com"
      }
    }
  }
}

📋 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

🔧 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

Once configured, you can ask your MCP client to:

"List my email folders"
"Show the latest 5 emails in my inbox"
"Send an email with subject 'Test Email' to example@example.com"
"Search for emails containing the keyword 'invoice'"
"Get details of email with UID 1234"
"Download attachments from the email"

🤝 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! (｡♥‿♥｡)