MCP IMAP Server

A Model Context Protocol (MCP) server that enables Claude and other LLM applications to read emails via the IMAP protocol. This server provides secure, read-only access to email accounts from popular providers like Gmail, Outlook, Yahoo, and custom IMAP servers.

Features

• 🔐 Secure Authentication: Support for username/password authentication with secure credential handling
• 📧 Email Operations: Search, read, and manage emails with comprehensive filtering options
• 📁 Folder Management: List and navigate email folders/mailboxes
• 🏷️ Email Status: Mark emails as read/unread
• 🔍 Advanced Search: Search by sender, subject, date range, content, and read status
• 🌐 Provider Support: Pre-configured for Gmail, Outlook, Yahoo, iCloud, and custom IMAP servers
• 🛡️ Security First: Read-only access, no email sending or deletion capabilities
• ⚡ Performance: Efficient connection pooling and error handling

Quick Start

Installation

git clone <repository-url>
cd mcp-imap-server
npm install
npm run build

Configuration

Create a .env file in the project root:

# Required: IMAP server configuration
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your-email@gmail.com
IMAP_PASSWORD=your-app-password
IMAP_TLS=true

# Optional: Connection settings
IMAP_AUTH_TIMEOUT=3000
IMAP_CONN_TIMEOUT=10000
IMAP_KEEPALIVE_INTERVAL=10000
IMAP_IDLE_INTERVAL=300000
IMAP_FORCE_NOOP=false

Popular Email Provider Settings

Gmail

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_TLS=true

Outlook/Hotmail

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_TLS=true

Yahoo Mail

IMAP_HOST=imap.mail.yahoo.com
IMAP_PORT=993
IMAP_TLS=true

iCloud Mail

IMAP_HOST=imap.mail.me.com
IMAP_PORT=993
IMAP_TLS=true

Running the Server

# Development mode
npm run dev

# Production mode
npm run build
npm start

MCP Tools

The server exposes the following tools to MCP clients:

search_emails

Search for emails based on various criteria.

Parameters:

• sender (optional): Filter by sender email address or name
• subject (optional): Filter by subject line (partial match)
• dateFrom (optional): Start date for date range filter (ISO format: YYYY-MM-DD)
• dateTo (optional): End date for date range filter (ISO format: YYYY-MM-DD)
• content (optional): Search within email content/body text
• unread (optional): Filter by read status (true for unread only, false for read only)
• folder (optional): Folder to search in (defaults to INBOX)
• limit (optional): Maximum number of emails to return (1-100)

Example:

{
  "name": "search_emails",
  "arguments": {
    "sender": "notifications@github.com",
    "unread": true,
    "limit": 10
  }
}

get_email

Retrieve the full content of a specific email by its message ID.

Parameters:

• messageId (required): The message ID or UID of the email to retrieve
• folder (optional): Folder containing the email (defaults to INBOX)

Example:

{
  "name": "get_email",
  "arguments": {
    "messageId": "12345",
    "folder": "INBOX"
  }
}

list_folders

List all available email folders/mailboxes in the account.

Parameters:

• includeSpecial (optional): Include special folders like Sent, Drafts, etc.

Example:

{
  "name": "list_folders",
  "arguments": {
    "includeSpecial": true
  }
}

get_recent_emails

Get the most recent emails from a specific folder.

Parameters:

• folder (optional): Folder to get emails from (defaults to INBOX)
• limit (optional): Number of recent emails to retrieve (1-50, default: 10)
• unreadOnly (optional): Only return unread emails

Example:

{
  "name": "get_recent_emails",
  "arguments": {
    "folder": "INBOX",
    "limit": 5,
    "unreadOnly": true
  }
}

mark_as_read

Mark an email as read or unread.

Parameters:

• messageId

... View full README on GitHub