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

Quick Setup:

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

Gmail Example:

[email protected]
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 "[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 CLI Reference - All commands with examples
• 🔧 Installation Guide - Cross-platform setup instructions
• 🚨 Troubleshooting - Common issues and quick fixes
• 🏗️ Architecture - Technical details and MCP integration

Quick Links:

• Basic Operations - Send, read, delete emails
• Advanced Features - Search, forward, bulk operations
• Contact Management - 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": "[email protected]", 
  "subject": "Hello",
  "body": "Message from Claude!"
}

🔧 Complete MCP Documentation

🔐 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 Contributing Guidelines

📞 Support & Resources

Issues & Questions:

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

Key Resources:

• Installation Problems - Platform compatibility fixes
• Authentication Issues - Email provider setup
• Performance Optimization - Speed improvements

📄 License

MIT License - see LICENSE file for details.

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