Email MCP Server

Cross-platform email operations for MCP clients and CLI 🌍

A dual-purpose tool that works as:

• 🔌 MCP Server: Email capabilities for Claude Desktop and MCP clients
• ⚡ CLI Suite: 40+ commands for terminal email management

Universal compatibility: Works on Windows, macOS, Linux, and WSL with Gmail, Outlook, Yahoo, and any IMAP/SMTP providers.

✨ Features Overview

📧 Basic Operations: Send, read, get, delete emails | Mark read/unread
🔍 Advanced Features: Search, forward, reply, bulk operations | Draft & schedule
👥 Contact Management: Add, update, search, organize contacts by groups
🌐 Cross-Platform: Works identically on all platforms and terminals

🚀 Zero-Configuration Installation

🎯 One Command - Complete Setup:

npm install -g @0xshariq/email-mcp-server
# OR
pnpm install -g @0xshariq/email-mcp-server

✨ What Happens Automatically:

• ✅ Detects your platform (Windows/macOS/Linux/WSL)
• ✅ Creates 40+ command shortcuts globally
• ✅ Configures system PATH automatically
• ✅ Tests installation and provides setup guide
• ✅ Ready to use immediately - no manual steps!

🎬 Getting Started:

# Set up your email (one-time only):
email-setup

# Start sending emails:
email-send "[email protected]" "Hello" "Your message"

# Explore all commands:
email-cli --help

📖 Complete Installation Guide

⚙️ Configuration

🔧 The MCP server and CLI share the same environment configuration!

Local Development (Both Server & CLI)

# Copy and edit .env file
cp .env.example .env
nano .env  # Add your credentials

Global Installation (CLI)

Configure environment variables in your shell profile:

Linux: Add to ~/.bashrc

export EMAIL_USER="[email protected]"
export EMAIL_PASS="xxxx-xxxx-xxxx-xxxx"
export SMTP_HOST="smtp.gmail.com"
export SMTP_PORT="587"
export IMAP_HOST="imap.gmail.com"
export IMAP_PORT="993"

macOS: Add to ~/.zshrc (or ~/.bash_profile)

export EMAIL_USER="[email protected]"
export EMAIL_PASS="xxxx-xxxx-xxxx-xxxx"
# ... (same as Linux)

Windows: Set System Environment Variables

• Press Win + X → System → Advanced system settings
• Environment Variables → Add each variable

Quick Example (Gmail)

[email protected]
EMAIL_PASS=xxxx-xxxx-xxxx-xxxx  # App Password (not regular password)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
IMAP_HOST=imap.gmail.com
IMAP_PORT=993

📖 Complete Configuration Guide - Detailed setup for all platforms and providers

Setup Requirements:

1. Enable 2FA on your email provider
2. Generate App Password
3. Configure environment variables (locally or globally)

📋 Supports: Gmail, Outlook, Yahoo, and any IMAP/SMTP provider

💻 Usage

As MCP Server

npm start  # Starts MCP server for Claude Desktop

As CLI Tool (Cross-Platform)

# Works identically on Windows, macOS, Linux, WSL
email-send "[email protected]" "Subject" "Message"
email-read 10
contact-add "John Doe" "[email protected]" "work"
email-search --from "[email protected]" --unread

All 40+ commands work the same across all platforms!

📚 Documentation

Complete documentation for all features and platforms:

📖 Core Documentation

| Document | Description | |----------|-------------| | Configuration Guide | Comprehensive environment setup for CLI and MCP server (local and global) | | Installation Guide | Cross-platform installation instructions (Windows, macOS, Linux, WSL) | | CLI Reference | Complete reference for all 40+ CLI commands with examples | | CLI Usage | Top-level CLI usage and setup commands | | Commands Reference | Detailed command documentation with options and examples |

🔧 Technical Documentation

| Document | Description | |----------|-------------| | Architecture | System architecture, data models, and design decisions | | Troubleshooting | Common issues and solutions for all platforms | | Windows Guide | Windows-specific installation and configuration | | Publishing Guide | Package publishing and versioning strategy | | Restructure Summary | v2.0 TypeScript migration details |

🚀 Quick Start Guides

First Time Setup:

1. Installation: INSTALL.md
2. Configuration: CONFIGURATION.md
3. First Commands: CLI_REFERENCE.md

Having Issues?

• Start with troubleshooting.md
• Check CONFIGURATION.md for setup issues
• See WINDOWS.md for Windows-specific problems

Development & Contributing:

• architecture.md - Understand the codebase
• PUBLISHING.md - Release process
• RESTRUCTURE_SUMMARY.md - Recent changes

🎯 By Use Case

As CLI User:

• CLI_REFERENCE.md - All commands
• CONFIGURATION.md - Setup for global CLI
• troubleshooting.md - Fix issues

As MCP Server User:

• CONFIGURATION.md - Environment setup
• architecture.md - MCP server details
• troubleshooting.md - Server configuration

As Developer:

• architecture.md - System design
• RESTRUCTURE_SUMMARY.md - Code organization
• PUBLISHING.md - Release workflow

MCP Server Integration

When running as an MCP server, all email operations are available as structured tools for Claude Desktop and other MCP clients.

Available Tools:

• Email operations: send, read, search, forward, reply, delete
• Contact management: add, update, search, organize
• Bulk operations: batch sending, scheduling, drafts

Usage in Claude Desktop:

{
  "to": "[email protected]", 
  "subject": "Hello",
  "body": "Message from Claude!"
}

📖 Configuration: See CONFIGURATION.md

🔐 Security & Best Practices

• Use App Passwords (not regular passwords)
• Keep .env secure (never commit to git)
• Respect rate limits for bulk operations
• Use HTTPS/TLS for all connections

🛠️ Development & Contributing

Quick Development Setup:

git clone https://github.com/0xshariq/email-mcp-server.git
cd email-mcp-server
npm install          # Install dependencies
npm run build        # Compile TypeScript
npm link             # Test locally

Project Structure:

email-mcp-server/
├── cli/            # CLI implementation (Commander.js)
├── server/         # MCP server implementation
├── src/lib/        # Shared email & contact services
├── dist/           # Compiled JavaScript
└── docs/           # Complete documentation

Key Technologies:

• TypeScript 5.8+ with strict mode
• Commander.js 14+ for CLI
• Nodemailer 7+ for SMTP
• IMAP-Simple 5+ for IMAP
• MCP SDK 1.15+ for server

Documentation for Developers:

• Architecture Guide - System design and decisions
• Restructure Summary - v2.0 TypeScript migration
• Publishing Guide - Release process

Contributing: Fork → Branch → PR. See Contributing Guidelines

📞 Support & Resources

Issues & Questions:

• 🚨 Troubleshooting Guide - Quick fixes for common issues
• 🐛 GitHub Issues - Report bugs or request features
• 💬 GitHub Discussions - Ask questions and share ideas

Documentation by Topic:

• Installation Problems - Platform-specific setup
• Configuration Issues - Environment variables setup
• Authentication Errors - Email provider setup
• Command Reference - All CLI commands
• Performance Tips - Speed improvements

All Documentation: See docs/ folder for complete guides

📄 License

MIT License - see LICENSE file for details.

🌟 Star this repo if it helps you manage emails efficiently across platforms!

Version: 2.0.0
Last Updated: December 20, 2025