# IMAP Email MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides email capabilities to Claude Code, Claude Desktop, Cursor, and other MCP-compatible AI tools. Connect to any IMAP/SMTP email provider to read, search, compose, and manage emails directly from your AI assistant.

## Quick Start

### Claude Code (CLI)

**Important:** Claude Code CLI uses `claude mcp add`, not config files.

```bash
claude mcp add imap-email -s user \
  -e IMAP_USER=you@example.com \
  -e IMAP_PASSWORD='your-app-password' \
  -e IMAP_HOST=imap.example.com \
  -- npx -y imap-email-mcp
```

> **Note:** If your password contains special shell characters (`%`, `^`, `*`, `$`, `!`, etc.), wrap it in single quotes as shown above.

> **Note:** Restart Claude Code after adding an MCP for the new tools to become available.

Verify with:
```bash
claude mcp list
claude mcp get imap-email
```

Remove with:
```bash
claude mcp remove imap-email -s user
```

### Cursor

Add new MCP server:
- **Name:** `imap-email`
- **Type:** `command`
- **Command:** `npx -y imap-email-mcp`

Then set environment variables in Cursor's MCP settings:
```
IMAP_USER=your-email@example.com
IMAP_PASSWORD=your-app-password
IMAP_HOST=imap.example.com
```

### Claude Desktop

Add to your config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "imap-email": {
      "command": "npx",
      "args": ["-y", "imap-email-mcp"],
      "env": {
        "IMAP_USER": "your-email@example.com",
        "IMAP_PASSWORD": "your-app-password",
        "IMAP_HOST": "imap.example.com"
      }
    }
  }
}
```

## Features

- **Read emails** - List and read emails from any folder
- **Search** - Search by subject, sender, or body content
- **Compose** - Create and save email drafts
- **Send** - Send emails directly via SMTP
- **Manage drafts** - List, read, update, and delete drafts
- **Delete emails** - Remove unwanted messages
- **Multi-provider support** - Works with Gmail, Outlook, Yahoo, Fastmail, and any standard IMAP provider

## Configuration

### Required Environment Variables

| Variable | Description |
|----------|-------------|
| `IMAP_USER` | Your email address |
| `IMAP_PASSWORD` | App password (not your main password!) |
| `IMAP_HOST` | IMAP server hostname |

### Optional Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `IMAP_PORT` | `993` | IMAP port |
| `IMAP_TLS` | `true` | Use TLS |
| `SMTP_HOST` | Same as IMAP_HOST | SMTP server hostname |
| `SMTP_PORT` | `465` | SMTP port |
| `SMTP_SECURE` | `true` | Use secure SMTP |

### Provider Settings

| Provider | IMAP_HOST | SMTP_HOST | Notes |
|----------|-----------|-----------|-------|
| **Gmail** | `imap.gmail.com` | `smtp.gmail.com` | [Create App Password](https://myaccount.google.com/apppasswords) |
| **Outlook** | `outlook.office365.com` | `smtp.office365.com` | Use port 587, SMTP_SECURE=false |
| **Yahoo** | `imap.mail.yahoo.com` | `smtp.mail.yahoo.com` | Generate App Password in settings |
| **Fastmail** | `imap.fastmail.com` | `smtp.fastmail.com` | App Password from Privacy & Security |
| **iCloud** | `imap.mail.me.com` | `smtp.mail.me.com` | [Generate App Password](https://appleid.apple.com/) |

## Available Tools

| Tool | Description |
|------|-------------|
| `list_folders` | List all email folders/mailboxes |
| `list_emails` | List emails with optional filtering |
| `get_email` | Get full email content by UID |
| `search_emails` | Search by subject, sender, or body |
| `list_drafts` | List all draft emails |
| `get_draft` | Get a specific draft by UID |
| `create_draft` | Create a new email draft |
| `update_draft` | Update an existing draft |
| `send_email` | Send an email directly |
| `delete_email` | Delete an email by UID |

## Usage Examples

Once configured, use natural language:

- "Check my inbox for unread emails"
- "Search for emails from john@example.com"
- "Create a draft email to sarah@example.com about the meeting tomorrow"
- "Show me my drafts folder"

## Security Best Practices

1. **Use App Passwords** - Never use your main account password
2. **Environment Variables** - Store credentials in env vars, not in code
3. **Review Before Sending** - Use `create_draft` instead of `send_email` to review first

## Troubleshooting

**Authentication failed**
- Verify your app password is correct
- Ensure IMAP access is enabled in your email provider's settings

**Drafts folder not found**
- The server tries common names (`Drafts`, `INBOX.Drafts`, `[Gmail]/Drafts`)
- Your provider may use a different folder name

**Connection timeout**
- Check your `IMAP_HOST` is correct
- Verify port 993 is not blocked by firewall

## Alternative Installation

### Install globally
```bash
npm install -g imap-email-mcp
imap-email-mcp
```

### Clone and run
```bash
git clone https://github.com/jdickey1/imap-email-mcp.git
cd imap-email-mcp
npm install
node index.js
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [npm package](https://www.npmjs.com/package/imap-email-mcp)
- [GitHub repo](https://github.com/jdickey1/imap-email-mcp)
- [MCP Protocol](https://modelcontextprotocol.io/)