email-smtp-imap-mcp 2.0.0

package/.env.example

@@ -0,0 +1,48 @@
+# Email MCP Server Configuration
+
+# ===== OPTION 1: Multiple Accounts (JSON) =====
+# Configure multiple email accounts in JSON format
+EMAIL_ACCOUNTS_JSON='{
+  "work": {
+    "smtp_host": "smtp.mail.me.com",
+    "smtp_port": 587,
+    "smtp_secure": false,
+    "smtp_user": "your-email@icloud.com",
+    "smtp_pass": "your-app-specific-password",
+    "imap_host": "imap.mail.me.com",
+    "imap_port": 993,
+    "imap_secure": true,
+    "default_from_name": "Your Name"
+  },
+  "personal": {
+    "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,
+    "default_from_name": "Your Name"
+  }
+}'
+
+# Default account to use if not specified in tool calls
+DEFAULT_EMAIL_ACCOUNT="work"
+
+# ===== OPTION 2: Single Account (Individual Variables) =====
+# Use these if you only have one email account
+# SMTP_HOST="smtp.mail.me.com"
+# SMTP_PORT=587
+# SMTP_SECURE=false
+# SMTP_USER="your-email@icloud.com"
+# SMTP_PASS="your-app-specific-password"
+# IMAP_HOST="imap.mail.me.com"
+# IMAP_PORT=993
+# IMAP_SECURE=true
+# DEFAULT_FROM_NAME="Your Name"
+
+# ===== NOTES =====
+# For Gmail: Use App-Specific Passwords (not your regular password)
+# For iCloud: Use App-Specific Passwords
+# For other providers: Check their SMTP/IMAP settings documentation

package/README.md

@@ -0,0 +1,87 @@
+# Email MCP Server
+
+A clean, simple MCP server for email operations (SMTP + IMAP).
+
+## Features
+
+- ✅ **Send emails** (HTML + attachments)
+- ✅ **Search emails** (flexible filters)
+- ✅ **Reply/Forward** (with threading)
+- ✅ **Organize** (mark read, archive, flag)
+- ✅ **List folders**
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install
+npm run build
+```
+
+### 2. Configure
+
+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
+```
+
+### 3. Add to MCP-Supported Software
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "email": {
+      "command": "node",
+      "args": ["/absolute/path/to/email-smtp-imap-mcp/build/index.js"],
+      "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"
+      }
+    }
+  }
+}
+```
+
+**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.
+
+Restart Claude Desktop to load the MCP server.
+
+## 5 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 |
+
+## Usage Examples
+
+```
+"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
+
+- **QUICK_REFERENCE.md** - Command examples
+- **DESIGN.md** - Architecture details
+- **SETUP_COMPLETE.md** - Full setup guide
+
+## License
+
+MIT

package/build/accountManager.js

@@ -0,0 +1,66 @@
+/**
+ * Email account configuration management
+ */
+/**
+ * Load email accounts from environment variables
+ */
+export function loadAccounts() {
+    // Try JSON configuration first
+    const jsonConfig = process.env.EMAIL_ACCOUNTS_JSON;
+    if (jsonConfig) {
+        try {
+            return JSON.parse(jsonConfig);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse EMAIL_ACCOUNTS_JSON: ${error}`);
+        }
+    }
+    // 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
+        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.');
+    }
+    // Use DEFAULT_EMAIL_ACCOUNT as the account name, or "default"
+    const accountName = process.env.DEFAULT_EMAIL_ACCOUNT || 'default';
+    return {
+        [accountName]: singleAccount
+    };
+}
+/**
+ * Get a specific email account by name
+ */
+export function getAccount(accountName) {
+    const accounts = loadAccounts();
+    // If no account name specified, use the default
+    if (!accountName) {
+        const defaultAccountName = process.env.DEFAULT_EMAIL_ACCOUNT || Object.keys(accounts)[0];
+        if (!defaultAccountName) {
+            throw new Error('No email accounts configured');
+        }
+        accountName = defaultAccountName;
+    }
+    const config = accounts[accountName];
+    if (!config) {
+        const availableAccounts = Object.keys(accounts).join(', ');
+        throw new Error(`Account "${accountName}" not found. Available accounts: ${availableAccounts}`);
+    }
+    return { name: accountName, config };
+}
+/**
+ * List all configured accounts
+ */
+export function listAccounts() {
+    const accounts = loadAccounts();
+    return Object.keys(accounts);
+}

package/build/config.js

@@ -0,0 +1,238 @@
+import fs from 'fs-extra';
+import * as path from 'path';
+import * as os from 'os';
+import { logToFile } from "./index.js";
+// Define paths for configuration and data storage
+export const CONFIG_DIR = path.join(os.homedir(), '.smtp-mcp-server');
+export const TEMPLATES_DIR = path.join(CONFIG_DIR, 'templates');
+export const SMTP_CONFIG_FILE = path.join(CONFIG_DIR, 'smtp-config.json');
+export const LOG_FILE = path.join(CONFIG_DIR, 'email-logs.json');
+// Default SMTP configuration
+export const DEFAULT_SMTP_CONFIG = {
+    smtpServers: [
+        {
+            id: 'example-smtp',
+            name: 'Example SMTP',
+            host: 'smtp.example.com',
+            port: 587,
+            secure: false,
+            auth: {
+                user: 'username',
+                pass: 'password'
+            },
+            isDefault: true
+        }
+    ],
+    rateLimit: {
+        enabled: true,
+        messagesPerMinute: 30
+    }
+};
+// Default email template
+export const DEFAULT_TEMPLATE = {
+    id: 'default',
+    name: 'Default Template',
+    subject: 'Default Subject',
+    body: 'Hello {{name}},\n\nThis is a default email template.\n\nBest regards,\nThe Team',
+    isDefault: true
+};
+// Example business template
+export const BUSINESS_TEMPLATE = {
+    id: 'business-outreach',
+    name: 'Business Outreach',
+    subject: 'Partnership Opportunity - {{company}}',
+    body: `Dear {{name}},
+
+I hope this email finds you well. I'm reaching out to explore potential collaboration opportunities between our organizations.
+
+We've been following {{company}}'s achievements and believe there could be synergies worth exploring.
+
+Would you be available for a brief call to discuss this further? I'd love to learn more about your current initiatives.
+
+Best regards,
+{{sender_name}}
+{{sender_email}}`,
+    isDefault: false
+};
+// Example newsletter template
+export const NEWSLETTER_TEMPLATE = {
+    id: 'newsletter',
+    name: 'Monthly Newsletter',
+    subject: '{{month}} Newsletter - {{company}}',
+    body: `Dear {{name}},
+
+Welcome to our {{month}} newsletter! 
+
+{{main_content}}
+
+We hope you found this update valuable. If you have any questions, please don't hesitate to contact us.
+
+Best regards,
+The {{company}} Team
+{{contact_email}}`,
+    isDefault: false
+};
+/**
+ * Ensure all necessary directories and config files exist
+ */
+export async function ensureConfigDirectories() {
+    try {
+        // Create config directory if it doesn't exist
+        await fs.ensureDir(CONFIG_DIR);
+        await fs.ensureDir(TEMPLATES_DIR);
+        // Create default SMTP config if it doesn't exist
+        if (!await fs.pathExists(SMTP_CONFIG_FILE)) {
+            await fs.writeJson(SMTP_CONFIG_FILE, DEFAULT_SMTP_CONFIG, { spaces: 2 });
+        }
+        // Create default template if it doesn't exist
+        const defaultTemplatePath = path.join(TEMPLATES_DIR, 'default.json');
+        if (!await fs.pathExists(defaultTemplatePath)) {
+            await fs.writeJson(defaultTemplatePath, DEFAULT_TEMPLATE, { spaces: 2 });
+        }
+        // Create business template if it doesn't exist
+        const businessTemplatePath = path.join(TEMPLATES_DIR, 'business-outreach.json');
+        if (!await fs.pathExists(businessTemplatePath)) {
+            await fs.writeJson(businessTemplatePath, BUSINESS_TEMPLATE, { spaces: 2 });
+        }
+        // Create newsletter template if it doesn't exist
+        const newsletterTemplatePath = path.join(TEMPLATES_DIR, 'newsletter.json');
+        if (!await fs.pathExists(newsletterTemplatePath)) {
+            await fs.writeJson(newsletterTemplatePath, NEWSLETTER_TEMPLATE, { spaces: 2 });
+        }
+        // Create log file if it doesn't exist
+        if (!await fs.pathExists(LOG_FILE)) {
+            await fs.writeJson(LOG_FILE, [], { spaces: 2 });
+        }
+    }
+    catch (error) {
+        logToFile(`Error ensuring config directories: ${error}`);
+        throw error;
+    }
+}
+/**
+ * Get SMTP configurations
+ */
+export async function getSmtpConfigs() {
+    try {
+        const config = await fs.readJson(SMTP_CONFIG_FILE);
+        return config.smtpServers || [];
+    }
+    catch (error) {
+        logToFile('Error reading SMTP config:');
+        return DEFAULT_SMTP_CONFIG.smtpServers;
+    }
+}
+/**
+ * Get default SMTP configuration
+ */
+export async function getDefaultSmtpConfig() {
+    const configs = await getSmtpConfigs();
+    return configs.find(config => config.isDefault) || configs[0] || DEFAULT_SMTP_CONFIG.smtpServers[0];
+}
+/**
+ * Save SMTP configurations
+ */
+export async function saveSmtpConfigs(configs) {
+    try {
+        const currentConfig = await fs.readJson(SMTP_CONFIG_FILE);
+        currentConfig.smtpServers = configs;
+        await fs.writeJson(SMTP_CONFIG_FILE, currentConfig, { spaces: 2 });
+        return true;
+    }
+    catch (error) {
+        logToFile('Error saving SMTP config:');
+        return false;
+    }
+}
+/**
+ * Get email templates
+ */
+export async function getEmailTemplates() {
+    try {
+        const files = await fs.readdir(TEMPLATES_DIR);
+        const templates = [];
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const templatePath = path.join(TEMPLATES_DIR, file);
+                const template = await fs.readJson(templatePath);
+                templates.push(template);
+            }
+        }
+        return templates;
+    }
+    catch (error) {
+        logToFile('Error reading email templates:');
+        return [DEFAULT_TEMPLATE, BUSINESS_TEMPLATE, NEWSLETTER_TEMPLATE];
+    }
+}
+/**
+ * Get default email template
+ */
+export async function getDefaultEmailTemplate() {
+    const templates = await getEmailTemplates();
+    return templates.find(template => template.isDefault) || templates[0] || DEFAULT_TEMPLATE;
+}
+/**
+ * Save email template
+ */
+export async function saveEmailTemplate(template) {
+    try {
+        const templatePath = path.join(TEMPLATES_DIR, `${template.id}.json`);
+        await fs.writeJson(templatePath, template, { spaces: 2 });
+        return true;
+    }
+    catch (error) {
+        logToFile('Error saving email template:');
+        return false;
+    }
+}
+/**
+ * Delete email template
+ */
+export async function deleteEmailTemplate(templateId) {
+    try {
+        const templatePath = path.join(TEMPLATES_DIR, `${templateId}.json`);
+        await fs.remove(templatePath);
+        return true;
+    }
+    catch (error) {
+        logToFile('Error deleting email template:');
+        return false;
+    }
+}
+/**
+ * Log email activity
+ */
+export async function logEmailActivity(entry) {
+    try {
+        let logs = [];
+        // Read existing logs if file exists
+        if (await fs.pathExists(LOG_FILE)) {
+            logs = await fs.readJson(LOG_FILE);
+        }
+        // Add new log entry
+        logs.push(entry);
+        // Write updated logs
+        await fs.writeJson(LOG_FILE, logs, { spaces: 2 });
+        return true;
+    }
+    catch (error) {
+        logToFile('Error logging email activity:');
+        return false;
+    }
+}
+/**
+ * Get email logs
+ */
+export async function getEmailLogs() {
+    try {
+        if (await fs.pathExists(LOG_FILE)) {
+            return await fs.readJson(LOG_FILE);
+        }
+        return [];
+    }
+    catch (error) {
+        logToFile('Error reading email logs:');
+        return [];
+    }
+}

package/build/emailHandlers.js

@@ -0,0 +1,175 @@
+/**
+ * Tool request handlers for email operations
+ */
+import { getAccount } from './accountManager.js';
+import { searchEmails, modifyEmails, listFolders } from './imapService.js';
+import { sendEmail, replyToEmail, forwardEmail } from './smtpService.js';
+/**
+ * Handle emails_find tool
+ */
+export async function handleEmailsFind(args) {
+    try {
+        const { name, config } = getAccount(args.account_name);
+        const filters = args.filters || {};
+        const limit = args.limit || 20;
+        const includeContent = args.include_content || false;
+        const includeAttachments = args.include_attachments || false;
+        const emails = await searchEmails(config, filters, limit, includeContent, includeAttachments);
+        return JSON.stringify({
+            success: true,
+            account: name,
+            count: emails.length,
+            emails
+        }, null, 2);
+    }
+    catch (error) {
+        return JSON.stringify({
+            success: false,
+            error: error.message || 'Failed to search emails'
+        }, null, 2);
+    }
+}
+/**
+ * Handle emails_modify tool
+ */
+export async function handleEmailsModify(args) {
+    try {
+        const { name, config } = getAccount(args.account_name);
+        if (!args.email_ids || args.email_ids.length === 0) {
+            throw new Error('email_ids is required and must not be empty');
+        }
+        const result = await modifyEmails(config, args.email_ids, {
+            markRead: args.mark_read,
+            markUnread: args.mark_unread,
+            flag: args.flag,
+            unflag: args.unflag,
+            moveToFolder: args.move_to_folder
+        });
+        return JSON.stringify({
+            success: result.success,
+            account: name,
+            modified: result.modified,
+            total: args.email_ids.length,
+            errors: result.errors
+        }, null, 2);
+    }
+    catch (error) {
+        return JSON.stringify({
+            success: false,
+            error: error.message || 'Failed to modify emails'
+        }, null, 2);
+    }
+}
+/**
+ * Handle email_send tool
+ */
+export async function handleEmailSend(args) {
+    try {
+        const { name, config } = getAccount(args.account_name);
+        if (!args.to || args.to.length === 0) {
+            throw new Error('to is required and must not be empty');
+        }
+        if (!args.subject) {
+            throw new Error('subject is required');
+        }
+        if (!args.body) {
+            throw new Error('body is required');
+        }
+        const result = await sendEmail(config, {
+            to: args.to,
+            subject: args.subject,
+            body: args.body,
+            bodyType: args.body_type || 'html',
+            cc: args.cc,
+            bcc: args.bcc,
+            attachments: args.attachments,
+            fromName: config.default_from_name
+        });
+        return JSON.stringify({
+            success: result.success,
+            account: name,
+            message_id: result.messageId,
+            to: args.to,
+            subject: args.subject
+        }, null, 2);
+    }
+    catch (error) {
+        return JSON.stringify({
+            success: false,
+            error: error.message || 'Failed to send email'
+        }, null, 2);
+    }
+}
+/**
+ * Handle email_respond tool
+ */
+export async function handleEmailRespond(args) {
+    try {
+        const { name, config } = getAccount(args.account_name);
+        if (!args.email_id) {
+            throw new Error('email_id is required');
+        }
+        if (!args.body) {
+            throw new Error('body is required');
+        }
+        const responseType = args.response_type || 'reply';
+        let result;
+        if (responseType === 'forward') {
+            if (!args.to || args.to.length === 0) {
+                throw new Error('to is required for forward');
+            }
+            result = await forwardEmail(config, args.email_id, {
+                to: args.to,
+                body: args.body,
+                bodyType: args.body_type || 'html',
+                includeOriginal: args.include_original !== false,
+                includeAttachments: args.include_attachments !== false,
+                additionalAttachments: args.additional_attachments
+            });
+        }
+        else {
+            result = await replyToEmail(config, args.email_id, {
+                body: args.body,
+                bodyType: args.body_type || 'html',
+                replyAll: responseType === 'reply_all',
+                includeOriginal: args.include_original !== false,
+                includeAttachments: args.include_attachments !== false,
+                additionalAttachments: args.additional_attachments
+            });
+        }
+        return JSON.stringify({
+            success: result.success,
+            account: name,
+            message_id: result.messageId,
+            response_type: responseType,
+            original_email_id: args.email_id
+        }, null, 2);
+    }
+    catch (error) {
+        return JSON.stringify({
+            success: false,
+            error: error.message || 'Failed to respond to email'
+        }, null, 2);
+    }
+}
+/**
+ * Handle folders_list tool
+ */
+export async function handleFoldersList(args) {
+    try {
+        const { name, config } = getAccount(args.account_name);
+        const folders = await listFolders(config, args.include_counts || false);
+        return JSON.stringify({
+            success: true,
+            account: name,
+            count: folders.length,
+            folders
+        }, null, 2);
+    }
+    catch (error) {
+        return JSON.stringify({
+            success: false,
+            error: error.message || 'Failed to list folders'
+        }, null, 2);
+    }
+}