IMAP Email MCP Server

A Model Context Protocol (MCP) 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.

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:

claude mcp list
claude mcp get imap-email

Remove with:

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

{
  "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 | | 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 |

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

npm install -g imap-email-mcp
imap-email-mcp

Clone and run

git clone https://github.com/jdickey1/imap-email-mcp.git
cd imap-email-mcp
npm install
node index.js

License

MIT License - see LICENSE for details.

Links

• npm package
• GitHub repo
• MCP Protocol