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