Email MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to manage emails via SMTP and IMAP. Send emails, fetch unread messages, and create draft replies directly from conversations.

Features

• Send Emails - Send emails via SMTP with subject and body
• Fetch Unread Emails - Retrieve unread messages from your inbox
• Create Draft Replies - Generate and save draft responses to emails
• Multi-Provider Support - Works with Gmail, Outlook, and Yahoo
• Input Validation - Comprehensive validation and sanitization
• Type Safety - Full TypeScript implementation with runtime type guards

Architecture

Built with a clean, modular architecture following SOLID principles:

src/
├── index.ts                  # Main server entry point
├── config/
│   └── email-config.ts       # Multi-provider configuration
├── services/
│   ├── smtp-service.ts       # SMTP operations
│   ├── imap-service.ts       # IMAP operations (async/await)
│   └── email-formatter.ts    # Email formatting utilities
├── tools/
│   ├── send-email.ts         # Send email tool
│   ├── get-unread.ts         # Fetch unread emails tool
│   └── create-draft.ts       # Create draft reply tool
├── types/
│   ├── email.types.ts        # TypeScript type definitions
│   └── type-guards.ts        # Runtime type validation
└── utils/
    ├── validation.ts         # Input validation & sanitization
    └── text-utils.ts         # Text processing utilities

Installation

Prerequisites

• Node.js 18+
• An email account with SMTP/IMAP access
• For Gmail: App Password (not your regular password)

Setup

1. Clone the repository

   git clone https://github.com/yourusername/email-mcp-server.git
   cd email-mcp-server
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Configure environment variables (optional for standalone testing)

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

Configuration

Claude Desktop Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "email": {
      "command": "node",
      "args": ["/absolute/path/to/email-mcp-server/build/index.js"],
      "env": {
        "EMAIL_USER": "your-email@gmail.com",
        "EMAIL_APP_PASSWORD": "your-16-character-app-password",
        "EMAIL_PROVIDER": "gmail"
      }
    }
  }
}

Supported Providers

• Gmail (default)

  • SMTP: smtp.gmail.com:587
  • IMAP: imap.gmail.com:993
  • Requires App Password

• Outlook

  • SMTP: smtp-mail.outlook.com:587
  • IMAP: outlook.office365.com:993

• Yahoo

  • SMTP: smtp.mail.yahoo.com:587
  • IMAP: imap.mail.yahoo.com:993

Set EMAIL_PROVIDER to gmail, outlook, or yahoo.

Usage

Once configured, Claude Desktop can use these tools:

Send Email

Send an email to user@example.com with subject "Meeting Tomorrow"
and body "Let's meet at 2 PM to discuss the project."

Fetch Unread Emails

Show me my last 5 unread emails

Create Draft Reply

Create a draft reply to email ID 123 from user@example.com

Security

• Input Validation: Email addresses, subject lines, and body content are validated
• Size Limits:
  • Subject lines: 998 characters (RFC 2822)
  • Email body: 500KB
• Content Sanitization: Control characters removed to prevent injection
• No Credential Storage: Credentials passed via environment variables only
• Type Safety: Runtime type guards prevent invalid tool arguments

Development

Building

npm run build       # Compile TypeScript
npm run watch      # Watch mode for development

Project Structure

• Functional Programming: All services use pure functions, no classes
• Separation of Concerns: Clear boundaries between config, services, tools, and utilities
• Type Guards: Runtime validation with TypeScript type narrowing
• Error Handling: Comprehensive error messages with context

Technical Highlights

Async/Await IMAP

Converted callback-based IMAP library to clean async/await:

export async function getUnreadEmails(limit: number = 10): Promise<Email[]> {
  const imap = await createConnection();
  try {
    await openBox(imap, "INBOX", false);
    const results = await search(imap, ["UNSEEN"]);
    // ... fetch and parse
  } finally {
    imap.end();
  }
}

Runtime Type Validation

Type guards ensure type safety at runtime:

export function isSendEmailParams(args: unknown): args is SendEmailParams {
  const obj = args as Record<string, unknown>;
  return (
    typeof obj === "object" &&
    obj !== null &&
    typeof obj.to === "string" &&
    typeof obj.subject === "string" &&
    typeof obj.body === "string"
  );
}

Multi-Provider Configuration

Easily switch between email providers:

export function getProvider(): EmailProvider {
  const provider = process.env.EMAIL_PROVIDER?.toLowerCase() || "gmail";
  switch (provider) {
    case "gmail": return { /* Gmail config */ };
    case "outlook": return { /* Outlook config */ };
    // ...
  }
}

License

MIT

Contributing

Contributions welcome! Please ensure:

• TypeScript compiles without errors
• Code follows functional programming patterns
• Input validation is maintained
• No credentials are committed