# 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](https://myaccount.google.com/apppasswords) (not your regular password)

### Setup

1. **Clone the repository**
   ```bash
   git clone https://github.com/yourusername/email-mcp-server.git
   cd email-mcp-server
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Build the project**
   ```bash
   npm run build
   ```

4. **Configure environment variables** (optional for standalone testing)
   ```bash
   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):

```json
{
  "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](https://myaccount.google.com/apppasswords)

- **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
```bash
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:
```typescript
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:
```typescript
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:
```typescript
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