Back to packageRELEASE DETAILS

1.6.1

npm

@0xshariq/email-mcp-server

A MCP Server + CLI Tool that perform email operations

Published4 Oct 2025

Direct dependencies10

Transitive dependenciesNot calculated

README

Current package documentation

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

📖 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="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 settings
Environment 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 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

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:

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 .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

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 10

Native requirements

10 direct targetsNot calculated transitive count

Package / target	Requirement	Relationship
ora Environment { "local_name": "ora", "alias": false, "peer_metadata": null }	`^9.0.0`	runtime
chalk Environment { "local_name": "chalk", "alias": false, "peer_metadata": null }	`^5.5.0`	runtime
nodemailer Environment { "local_name": "nodemailer", "alias": false, "peer_metadata": null }	`^7.0.6`	runtime
imap-simple Environment { "local_name": "imap-simple", "alias": false, "peer_metadata": null }	`^5.1.0`	runtime
@modelcontextprotocol/sdk Environment { "local_name": "@modelcontextprotocol/sdk", "alias": false, "peer_metadata": null }	`^1.15.1`	runtime
@modelcontextprotocol/inspector Environment { "local_name": "@modelcontextprotocol/inspector", "alias": false, "peer_metadata": null }	`^0.16.1`	runtime
typescript Environment { "local_name": "typescript", "alias": false, "peer_metadata": null }	`^5.8.3`	development
@types/node Environment { "local_name": "@types/node", "alias": false, "peer_metadata": null }	`^24.0.14`	development
@types/nodemailer Environment { "local_name": "@types/nodemailer", "alias": false, "peer_metadata": null }	`^7.0.2`	development
@types/imap-simple Environment { "local_name": "@types/imap-simple", "alias": false, "peer_metadata": null }	`^4.2.10`	development

Distribution files

1 collected

Distribution 1

Source distribution

Source file

Checksums from source

{
  "shasum": "58d5571c39a1825edd4258fbf71aaa32fe195fc5",
  "tarball": "https://registry.npmjs.org/@0xshariq/email-mcp-server/-/email-mcp-server-1.6.1.tgz",
  "fileCount": 30,
  "integrity": "sha512-o2hLgIb6UiTBsVIPWTdHSzEnnz78nclouqt8bJ5sBztVWl+nZKkxLW3Rgz8txawePKf7DNlsPEeHG0LTBxaN4w==",
  "signatures": [
    {
      "sig": "MEUCIEx/GwyuuXY8m0fUUfkIxHQTj/pKQ8ExVvV5FG+OJU+RAiEA/RUVXO4Ki0X5jv0kA7ECdS/6B9LSq5qV0g9+8I+ORWA=",
      "keyid": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"
    }
  ],
  "unpackedSize": 196149
}

Repository

PENDING

0xshariq/email-mcp-server

Shared repository data · GitHub

License detected in repository: Not collected

Metadata history

Meaningful changes

Current collected state Current

Observed since 21 Oct, 11:26 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:80fa0fcd6fd9ac18cced74fce18ed87cd7b29361f8d6a52c02eb162672a5f66a

Other collected versions

2.0.112 Jan 2.0.020 Dec 1.7.111 Oct 1.7.011 Oct 1.6.03 Oct 1.5.23 Oct View all collected versions →