0xshariq/email-mcp-server

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 "user@example.com" "Hello" "Your message"

# Explore all commands:
email-cli --help

📖

⚙️ Configuration

Quick Setup:

cp .env.example .env
# Edit .env with your email credentials

Gmail Example:

EMAIL_USER=your-email@gmail.com
EMAIL_PASS=xxxx-xxxx-xxxx-xxxx  # App Password (not regular password)

Setup Requirements:

1. Enable 2FA on your email provider
2. Generate App Password
3. Configure SMTP/IMAP settings

📋 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 "user@example.com" "Subject" "Message"
email-read 10
contact-add "John Doe" "john@example.com" "work"
email-search --from "boss@company.com" --unread

All 40+ commands work the same across all platforms!

📚 Documentation

• 📖 - All commands with examples
• 🔧 - Cross-platform setup instructions
• 🚨 - Common issues and quick fixes
• 🏗️ - Technical details and MCP integration

Quick Links:

• - Send, read, delete emails
• - Search, forward, bulk operations
• - Address book management

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": "user@example.com", 
  "subject": "Hello",
  "body": "Message from Claude!"
}

🔧

🔐 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 && npm run build
npm link  # Test locally

Contributing: Fork → Branch → PR. See

📞 Support & Resources

Issues & Questions:

• 🚨 - Quick fixes for common issues
• 🐛 GitHub Issues - Report bugs or request features
• 📖 - Detailed guides and references

Key Resources:

• - Platform compatibility fixes
• - Email provider setup
• - Speed improvements

📄 License

MIT License - see file for details.

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