jdickey1/imap-email-mcp

11 stars 10 forks Quality 72 Trend 18MIT

MCP server for Claude Code that provides email capabilities through IMAP/SMTP. Read, search, compose, and manage emails from any IMAP provider.

Overview

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. Claude Code CLI uses claude mcp add, not config files. If your password contains special shell characters (%, ^, *, $, !, etc.), wrap it in single quotes as shown above. Restart Claude Code after adding an MCP for the new tools to become available. Add new MCP server: - imap-email - command - npx -y imap-email-mcp Then set environment variables in Cursor's MCP settings: Add to your config file: - ~/Library/Application Support/Claude/claude_desktop_config.json - %APPDATA%\Claude\claude_desktop_config.

README

IMAP Email MCP Server

Quick Start

Claude Code (CLI)

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

claude mcp add imap-email -s user \
  -e [email protected] \
  -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:

[email protected]
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": "[email protected]",
        "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 [email protected]”
“Create a draft email to [email protected] about the meeting tomorrow”
“Show me my drafts folder”

Security Best Practices

Use App Passwords - Never use your main account password
Environment Variables - Store credentials in env vars, not in code
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

View the full README on GitHub

Install

npx -y imap-email-mcp

New to MCP? Start with the mcpskill.org guide →

Configuration

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