email-mcp-server
Provides tools for sending, reading, searching, forwarding, replying to, and deleting emails, as well as managing contacts, via Gmail's IMAP and SMTP services.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
Related MCP server: @marlinjai/email-mcp
๐ 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๐ 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 credentialsGlobal Installation (CLI)
Configure environment variables in your shell profile:
Linux: Add to ~/.bashrc
export EMAIL_USER="your-email@gmail.com"
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="your-email@gmail.com"
export EMAIL_PASS="xxxx-xxxx-xxxx-xxxx"
# ... (same as Linux)Windows: Set System Environment Variables
Press
Win + Xโ System โ Advanced system settingsEnvironment Variables โ Add each variable
Quick Example (Gmail)
EMAIL_USER=your-email@gmail.com
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:
Enable 2FA on your email provider
Generate App Password
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 DesktopAs 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" --unreadAll 40+ commands work the same across all platforms!
๐ Documentation
Complete documentation for all features and platforms:
๐ Core Documentation
Document | Description |
Comprehensive environment setup for CLI and MCP server (local and global) | |
Cross-platform installation instructions (Windows, macOS, Linux, WSL) | |
Complete reference for all 40+ CLI commands with examples | |
Top-level CLI usage and setup commands | |
Detailed command documentation with options and examples |
๐ง Technical Documentation
Document | Description |
System architecture, data models, and design decisions | |
Common issues and solutions for all platforms | |
Windows-specific installation and configuration | |
Package publishing and versioning strategy | |
v2.0 TypeScript migration details |
๐ Quick Start Guides
First Time Setup:
Installation: INSTALL.md
Configuration: CONFIGURATION.md
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": "user@example.com",
"subject": "Hello",
"body": "Message from Claude!"
}๐ Configuration: See CONFIGURATION.md
๐ Security & Best Practices
Use App Passwords (not regular passwords)
Keep
.envsecure (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 locallyProject Structure:
email-mcp-server/
โโโ cli/ # CLI implementation (Commander.js)
โโโ server/ # MCP server implementation
โโโ src/lib/ # Shared email & contact services
โโโ dist/ # Compiled JavaScript
โโโ docs/ # Complete documentationKey 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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
This server cannot be deployed
Maintenance
Related MCP Connectors
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Email infrastructure for AI agents โ send, receive, search, and reply to email over MCP.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Related MCP Servers
- FlicenseAqualityDmaintenanceA lightweight MCP server for personal Microsoft Outlook/Hotmail accounts, enabling email search, reading, attachment management, and folder operations via Microsoft Graph API with OAuth device-code flow.61-
- AlicenseBqualityBmaintenanceA unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers, enabling search, send, organize, and batch operations.36208 npm26MIT
- AlicenseAqualityDmaintenanceMCP server that enables email management (send, read, search, delete, etc.) via IMAP/SMTP, compatible with Gmail, Outlook, Yahoo, iCloud, and other standard mail servers.1139 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceA minimal MCP server for reading and sending emails via IMAP/SMTP, supporting multiple accounts in a single instance with zero external dependencies.1-