email-smtp-imap-mcp 2.0.0 → 2.0.4

package/.env.example

@@ -9,6 +9,8 @@ EMAIL_ACCOUNTS_JSON='{
     "smtp_secure": false,
     "smtp_user": "your-email@icloud.com",
     "smtp_pass": "your-app-specific-password",
+    "imap_user": "your-email@icloud.com",
+    "imap_pass": "your-app-specific-password",
     "imap_host": "imap.mail.me.com",
     "imap_port": 993,
     "imap_secure": true,
@@ -20,6 +22,8 @@ EMAIL_ACCOUNTS_JSON='{
     "smtp_secure": false,
     "smtp_user": "your-email@gmail.com",
     "smtp_pass": "your-app-specific-password",
+    "imap_user": "your-email@gmail.com",
+    "imap_pass": "your-app-specific-password",
     "imap_host": "imap.gmail.com",
     "imap_port": 993,
     "imap_secure": true,
@@ -37,9 +41,15 @@ DEFAULT_EMAIL_ACCOUNT="work"
 # SMTP_SECURE=false
 # SMTP_USER="your-email@icloud.com"
 # SMTP_PASS="your-app-specific-password"
+# SMTP_USERNAME="your-email@icloud.com"        # Alias for SMTP_USER
+# SMTP_PASSWORD="your-app-specific-password"   # Alias for SMTP_PASS
 # IMAP_HOST="imap.mail.me.com"
 # IMAP_PORT=993
 # IMAP_SECURE=true
+# IMAP_USER="your-email@icloud.com"
+# IMAP_PASS="your-app-specific-password"
+# IMAP_USERNAME="your-email@icloud.com"        # Alias for IMAP_USER
+# IMAP_PASSWORD="your-app-specific-password"   # Alias for IMAP_PASS
 # DEFAULT_FROM_NAME="Your Name"
 
 # ===== NOTES =====

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sami Halawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,38 +1,36 @@
 # Email MCP Server
 
-A clean, simple MCP server for email operations (SMTP + IMAP).
+A clean, simple stdio MCP server for email operations supporting both SMTP (sending) and IMAP (reading).
+
+[![npm version](https://badge.fury.io/js/email-smtp-imap-mcp.svg)](https://www.npmjs.com/package/email-smtp-imap-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- ✅ **Send emails** (HTML + attachments)
-- ✅ **Search emails** (flexible filters)
-- ✅ **Reply/Forward** (with threading)
+- ✅ **Send emails** with HTML and attachments
+- ✅ **Search emails** with flexible filters
+- ✅ **Reply/Forward** with proper threading
 - ✅ **Organize** (mark read, archive, flag)
-- ✅ **List folders**
+- ✅ **Multi-account support** for managing multiple email accounts
+- ✅ **List folders** to browse your mailbox structure
 
 ## Quick Start
 
-### 1. Install
+### Installation
 
 ```bash
-npm install
-npm run build
+npx -y email-smtp-imap-mcp
 ```
 
-### 2. Configure
+Or install globally:
 
-Create `.env`:
-
-```env
-EMAIL_ACCOUNTS_JSON={"icloud":{"smtp":{"host":"smtp.mail.me.com","port":587,"user":"your@icloud.com","password":"your-app-password"},"imap":{"host":"imap.mail.me.com","port":993},"default_from_name":"Your Name","sender_emails":["your@icloud.com","alias@domain.com"]}}
-DEFAULT_EMAIL_ACCOUNT=icloud
+```bash
+npm install -g email-smtp-imap-mcp
 ```
 
-### 3. Add to MCP-Supported Software
+### Configuration
 
-#### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
+Add to your Claude Desktop config file:
 
 **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -41,47 +39,121 @@ Add to your `claude_desktop_config.json`:
 {
   "mcpServers": {
     "email": {
-      "command": "node",
-      "args": ["/absolute/path/to/email-smtp-imap-mcp/build/index.js"],
+      "command": "npx",
+      "args": ["-y", "email-smtp-imap-mcp"],
       "env": {
-        "EMAIL_ACCOUNTS_JSON": "{\"icloud\":{\"smtp\":{\"host\":\"smtp.mail.me.com\",\"port\":587,\"user\":\"your@icloud.com\",\"password\":\"your-app-password\"},\"imap\":{\"host\":\"imap.mail.me.com\",\"port\":993},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"your@icloud.com\"]}}",
-        "DEFAULT_EMAIL_ACCOUNT": "icloud"
+        "EMAIL_ACCOUNTS_JSON": "{\"work\":{\"smtp\":{\"host\":\"smtp.gmail.com\",\"port\":587,\"user\":\"your@gmail.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993,\"user\":\"your@gmail.com\",\"password\":\"app-password\"},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"your@gmail.com\"]}}",
+        "DEFAULT_EMAIL_ACCOUNT": "work"
       }
     }
   }
 }
 ```
 
-**Note**: Replace `/absolute/path/to/email-smtp-imap-mcp` with your actual installation path. You can also use a `.env` file instead of inline env config.
+**⚠️ Important**: Restart Claude Desktop after adding this configuration.
+
+## Email Provider Settings
+
+### Gmail
+```json
+"EMAIL_ACCOUNTS_JSON": "{\"gmail\":{\"smtp\":{\"host\":\"smtp.gmail.com\",\"port\":587,\"user\":\"your@gmail.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993,\"user\":\"your@gmail.com\",\"password\":\"app-password\"},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"your@gmail.com\"]}}"
+```
+**Setup**: [Create App Password](https://support.google.com/accounts/answer/185833)
+
+### iCloud Mail
+```json
+"EMAIL_ACCOUNTS_JSON": "{\"icloud\":{\"smtp\":{\"host\":\"smtp.mail.me.com\",\"port\":587,\"user\":\"your@icloud.com\",\"password\":\"app-specific-password\"},\"imap\":{\"host\":\"imap.mail.me.com\",\"port\":993,\"user\":\"your@icloud.com\",\"password\":\"app-specific-password\"},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"your@icloud.com\"]}}"
+```
+**Setup**: [Generate App-Specific Password](https://support.apple.com/en-us/102654)
+
+### Outlook/Office 365
+```json
+"EMAIL_ACCOUNTS_JSON": "{\"outlook\":{\"smtp\":{\"host\":\"smtp-mail.outlook.com\",\"port\":587,\"user\":\"your@outlook.com\",\"password\":\"your-password\"},\"imap\":{\"host\":\"outlook.office365.com\",\"port\":993,\"user\":\"your@outlook.com\",\"password\":\"your-password\"},\"default_from_name\":\"Your Name\",\"sender_emails\":[\"your@outlook.com\"]}}"
+```
+
+### Multiple Accounts
+```json
+"EMAIL_ACCOUNTS_JSON": "{\"work\":{\"smtp\":{\"host\":\"smtp.gmail.com\",\"port\":587,\"user\":\"work@company.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.gmail.com\",\"port\":993,\"user\":\"work@company.com\",\"password\":\"app-password\"},\"default_from_name\":\"John Doe\"},\"personal\":{\"smtp\":{\"host\":\"smtp.mail.me.com\",\"port\":587,\"user\":\"me@icloud.com\",\"password\":\"app-password\"},\"imap\":{\"host\":\"imap.mail.me.com\",\"port\":993,\"user\":\"me@icloud.com\",\"password\":\"app-password\"},\"default_from_name\":\"John\"}}",
+"DEFAULT_EMAIL_ACCOUNT": "work"
+```
 
-Restart Claude Desktop to load the MCP server.
+The server also accepts flat or single-account environment variables. For compatibility, `SMTP_USERNAME`/`SMTP_PASSWORD` are aliases for `SMTP_USER`/`SMTP_PASS`, `IMAP_USERNAME`/`IMAP_PASSWORD` are aliases for `IMAP_USER`/`IMAP_PASS`, and `IMAP_USER`/`IMAP_PASS` fall back to the SMTP credentials when omitted.
 
-## 5 Tools
+## Available Tools
 
-| Tool | Purpose |
-|------|---------|
-| `emails_find` | Search emails with filters |
-| `emails_modify` | Mark read, archive, flag |
-| `email_send` | Send new emails |
-| `email_respond` | Reply or forward |
-| `folders_list` | List folders |
+| Tool | Description |
+|------|-------------|
+| `emails_find` | Search emails with flexible filters (sender, subject, date, attachments, etc.) |
+| `emails_modify` | Mark as read/unread, flag, archive, or move emails |
+| `email_send` | Send new emails with HTML content and attachments |
+| `email_respond` | Reply or forward emails with proper threading |
+| `folders_list` | List all available email folders |
 
 ## Usage Examples
 
+Ask Claude to:
+
+- "Find unread emails from last week"
+- "Send an email to team@company.com about the meeting"
+- "Reply to the last email from Sarah"
+- "Archive all emails older than 30 days"
+- "List my email folders"
+- "Find emails with attachments from my boss"
+- "Mark all emails from newsletter@site.com as read"
+
+## Security Notes
+
+- **Never commit** `.env` files or credentials to version control
+- Use **app-specific passwords** or **app passwords**, not your main account password
+- The server runs **locally** on your machine - credentials stay private
+- All email connections use **TLS encryption** (ports 587 for SMTP, 993 for IMAP)
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/samihalawa/email-smtp-imap-mcp.git
+cd email-smtp-imap-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+npm start
 ```
-"Find unread emails from last week"
-"Send an email to team@company.com"
-"Reply to the last email from John"
-"Archive all emails older than 30 days"
-"List my email folders"
-```
 
-## Documentation
+## Troubleshooting
+
+### Authentication Errors
+- Make sure you're using an **app password**, not your regular password
+- For Gmail: [Create App Password](https://support.google.com/accounts/answer/185833)
+- For iCloud: [Generate App-Specific Password](https://support.apple.com/en-us/102654)
+
+### Server Not Starting
+- Verify your configuration JSON is properly escaped
+- Check that ports 587 (SMTP) and 993 (IMAP) are not blocked by your firewall
+- Restart Claude Desktop after configuration changes
 
-- **QUICK_REFERENCE.md** - Command examples
-- **DESIGN.md** - Architecture details
-- **SETUP_COMPLETE.md** - Full setup guide
+### Connection Issues
+- Confirm your email provider allows IMAP/SMTP access
+- Check your internet connection
+- Verify the SMTP/IMAP host and port settings for your provider
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Author
+
+**Sami Halawa** - [GitHub](https://github.com/samihalawa)
+
+---
+
+Made with ❤️ for the MCP community

package/build/accountManager.js

@@ -1,6 +1,48 @@
 /**
  * Email account configuration management
  */
+function firstDefined(...values) {
+    return values.find((value) => value !== undefined && value !== '') || '';
+}
+function parsePort(value, fallback) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number.parseInt(value, 10);
+        if (!Number.isNaN(parsed))
+            return parsed;
+    }
+    return fallback;
+}
+function toBoolean(value, fallback) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    if (typeof value === 'boolean')
+        return value;
+    return String(value).toLowerCase() === 'true';
+}
+function normalizeAccountConfig(cfg) {
+    const smtp = cfg.smtp || {};
+    const imap = cfg.imap || {};
+    const smtpUser = firstDefined(smtp.user, cfg.smtp_user, cfg.SMTP_USER, cfg.SMTP_USERNAME);
+    const smtpPass = firstDefined(smtp.password, smtp.pass, cfg.smtp_pass, cfg.SMTP_PASS, cfg.SMTP_PASSWORD);
+    const imapUser = firstDefined(imap.user, imap.username, cfg.imap_user, cfg.IMAP_USER, cfg.IMAP_USERNAME, smtpUser);
+    const imapPass = firstDefined(imap.password, imap.pass, cfg.imap_pass, cfg.IMAP_PASS, cfg.IMAP_PASSWORD, smtpPass);
+    return {
+        smtp_host: firstDefined(smtp.host, cfg.smtp_host, cfg.SMTP_HOST, cfg.SMTP_SERVER, cfg.MTP_SERVER),
+        smtp_port: parsePort(smtp.port ?? cfg.smtp_port ?? cfg.SMTP_PORT, 587),
+        smtp_secure: toBoolean(smtp.secure ?? cfg.smtp_secure ?? cfg.SMTP_SECURE, parsePort(smtp.port ?? cfg.smtp_port ?? cfg.SMTP_PORT, 587) === 465),
+        smtp_user: smtpUser,
+        smtp_pass: smtpPass,
+        imap_user: imapUser,
+        imap_pass: imapPass,
+        imap_host: firstDefined(imap.host, cfg.imap_host, cfg.IMAP_HOST, cfg.IMAP_SERVER),
+        imap_port: parsePort(imap.port ?? cfg.imap_port ?? cfg.IMAP_PORT, 993),
+        imap_secure: toBoolean(imap.secure ?? cfg.imap_secure ?? cfg.IMAP_SECURE, parsePort(imap.port ?? cfg.imap_port ?? cfg.IMAP_PORT, 993) === 993),
+        default_from_name: cfg.default_from_name || cfg.DEFAULT_FROM_NAME,
+        sender_emails: cfg.sender_emails || cfg.SENDER_EMAILS
+    };
+}
 /**
  * Load email accounts from environment variables
  */
@@ -9,7 +51,14 @@ export function loadAccounts() {
     const jsonConfig = process.env.EMAIL_ACCOUNTS_JSON;
     if (jsonConfig) {
         try {
-            return JSON.parse(jsonConfig);
+            const parsed = JSON.parse(jsonConfig);
+            // Transform nested structure to flat structure
+            const accounts = {};
+            for (const [accountName, config] of Object.entries(parsed)) {
+                const cfg = config;
+                accounts[accountName] = normalizeAccountConfig(cfg);
+            }
+            return accounts;
         }
         catch (error) {
             throw new Error(`Failed to parse EMAIL_ACCOUNTS_JSON: ${error}`);
@@ -17,19 +66,34 @@ export function loadAccounts() {
     }
     // Fall back to single account from individual ENV vars
     const singleAccount = {
-        smtp_host: process.env.SMTP_HOST || '',
-        smtp_port: parseInt(process.env.SMTP_PORT || '587'),
-        smtp_secure: process.env.SMTP_SECURE === 'true',
-        smtp_user: process.env.SMTP_USER || '',
-        smtp_pass: process.env.SMTP_PASS || '',
-        imap_host: process.env.IMAP_HOST || '',
-        imap_port: parseInt(process.env.IMAP_PORT || '993'),
-        imap_secure: process.env.IMAP_SECURE !== 'false', // Default to true
+        smtp_host: firstDefined(process.env.SMTP_HOST, process.env.SMTP_SERVER, process.env.MTP_SERVER),
+        smtp_port: parsePort(process.env.SMTP_PORT, 587),
+        smtp_secure: toBoolean(process.env.SMTP_SECURE, parsePort(process.env.SMTP_PORT, 587) === 465),
+        smtp_user: firstDefined(process.env.SMTP_USER, process.env.SMTP_USERNAME),
+        smtp_pass: firstDefined(process.env.SMTP_PASS, process.env.SMTP_PASSWORD),
+        imap_user: firstDefined(process.env.IMAP_USER, process.env.IMAP_USERNAME, process.env.SMTP_USER, process.env.SMTP_USERNAME),
+        imap_pass: firstDefined(process.env.IMAP_PASS, process.env.IMAP_PASSWORD, process.env.SMTP_PASS, process.env.SMTP_PASSWORD),
+        imap_host: firstDefined(process.env.IMAP_HOST, process.env.IMAP_SERVER),
+        imap_port: parsePort(process.env.IMAP_PORT, 993),
+        imap_secure: toBoolean(process.env.IMAP_SECURE, parsePort(process.env.IMAP_PORT, 993) === 993),
         default_from_name: process.env.DEFAULT_FROM_NAME
     };
     // Validate single account has required fields
-    if (!singleAccount.smtp_host || !singleAccount.smtp_user || !singleAccount.smtp_pass) {
-        throw new Error('Email account configuration not found. Set EMAIL_ACCOUNTS_JSON or individual SMTP_* variables.');
+    const missingFields = [];
+    if (!singleAccount.smtp_host)
+        missingFields.push('SMTP_HOST');
+    if (!singleAccount.smtp_user)
+        missingFields.push('SMTP_USER');
+    if (!singleAccount.smtp_pass)
+        missingFields.push('SMTP_PASS');
+    if (!singleAccount.imap_host)
+        missingFields.push('IMAP_HOST');
+    if (!singleAccount.imap_user)
+        missingFields.push('IMAP_USER');
+    if (!singleAccount.imap_pass)
+        missingFields.push('IMAP_PASS');
+    if (missingFields.length > 0) {
+        throw new Error(`Missing required email configuration: ${missingFields.join(', ')}. Set EMAIL_ACCOUNTS_JSON or individual environment variables.`);
     }
     // Use DEFAULT_EMAIL_ACCOUNT as the account name, or "default"
     const accountName = process.env.DEFAULT_EMAIL_ACCOUNT || 'default';

package/build/emailHandlers.js

@@ -18,6 +18,7 @@ export async function handleEmailsFind(args) {
         return JSON.stringify({
             success: true,
             account: name,
+            total_found: emails.length,
             count: emails.length,
             emails
         }, null, 2);