MCP IMAP Server

An MCP (Model Context Protocol) server for manipulating IMAP mailboxes with advanced email search and management capabilities.

Features

• ✅ Professional IMAP Connection Management - Robust connection handling with automatic reconnection
• ✅ Advanced Email Search - Search by sender, subject, date range, read status, and more
• ✅ SMTP Email Sending - Send emails with automatic IMAP credential fallback
• ✅ Smart Caching - Message-ID caching for improved reliability
• ✅ Self-Signed Certificate Support - Works with corporate email servers
• ✅ Comprehensive Error Handling - Professional-grade error reporting
• ✅ Security Limits - Built-in safety limits for all operations

Installation

npm install
npm run build

Available Tools

Configuration is handled entirely through environment variables - no manual configuration tool needed.

1. list_folders

List all available mailbox folders.

2. read_emails 📧

Read emails from a specific folder with enhanced filtering.

Parameters:

• folder: Folder to read from (default: "INBOX")
• limit: Number of emails to retrieve (1-50, default: 10)
• unseen: Only retrieve unseen emails (default: false)

3. search_emails 🔍 Enhanced!

Search emails with advanced filtering including date ranges, sender, subject, and read status.

Parameters:

• folder: Mailbox folder to search in (default: "INBOX")
• query: Search query with multiple formats supported
• limit: Number of emails to retrieve (1-100, default: 10)
• dateFrom: Search emails from this date (YYYY-MM-DD format, optional)
• dateTo: Search emails until this date (YYYY-MM-DD format, optional)

Supported Query Formats:

Search by Sender

FROM [email protected]

Search by Subject

SUBJECT keyword

Search by Content

BODY message text

Search by Date (in query)

SINCE 2024-01-01
BEFORE 2024-12-31

Search by Read Status

UNSEEN
SEEN

General Text Search

any text

Example Usage:

1. Search emails from a specific sender:

{
  "folder": "INBOX",
  "query": "FROM [email protected]",
  "limit": 20
}

2. Search emails by subject with date range:

{
  "folder": "INBOX",
  "query": "SUBJECT meeting",
  "dateFrom": "2024-08-01",
  "dateTo": "2024-08-31",
  "limit": 10
}

3. Search unread emails:

{
  "folder": "INBOX",
  "query": "UNSEEN",
  "limit": 50
}

4. Search emails since a specific date:

{
  "folder": "INBOX",
  "query": "SINCE 2024-08-01",
  "limit": 25
}

5. Combined search with date parameters:

{
  "folder": "INBOX",
  "query": "FROM [email protected]",
  "dateFrom": "2024-07-01",
  "dateTo": "2024-07-31",
  "limit": 30
}

Enhanced Response Format:

{
  "results": [
    {
      "uid": 12345,
      "subject": "Email Subject",
      "from": {
        "name": "Sender Name",
        "address": "[email protected]"
      },
      "to": [...],
      "date": "2024-08-06T10:30:00.000Z",
      "seen": true
    }
  ],
  "totalFound": 50,
  "returned": 10,
  "searchCriteria": {
    "from": "[email protected]",
    "since": "2024-08-01T00:00:00.000Z"
  },
  "folder": "INBOX",
  "limit": 10
}

4. read_single_email

Read a specific email by UID with full content including body and headers.

Parameters:

• uid: UID of the email to read
• folder: Folder containing the email (default: "INBOX")
• includeBody: Include email body content (default: true)
• includeHeaders: Include all email headers (default: false)

5. get_email_info

Get basic info and UIDs of recent emails (useful to find valid UIDs for read_single_email).

Parameters:

• folder: Folder to get info from (default: "INBOX")
• limit: Number of recent emails to get UIDs for (1-100, default: 20)

6. send_email ⚡

Send emails via SMTP with automatic IMAP credential fallback.

Parameters:

• to: Recipient email address (required)
• subject: Email subject (required)
• text: Plain text content (optional)
• html: HTML content (optional)
• cc: CC recipients (optional)
• bcc: BCC recipients (optional)
• replyTo: Reply-to address (optional)
• from: From address (optional, uses SMTP auth user if not specified)

Note: Either text or html content must be provided.

Security & Performance Limits

• Search emails: Maximum 100 results per query
• Read emails: Maximum 50 results per query
• Get email info: Maximum 100 results per query
• Date validation: Strict YYYY-MM-DD format required
• Connection timeout: 5 minutes for IMAP operations
• Automatic retry: Built-in fallback strategies for message retrieval

Usage

As standalone MCP server

npm run dev

As NPX package

npx mcp-imap

Global installation with npm link

npm link
mcp-imap

MCP Client Configuration

Claude Desktop Configuration

Add this configuration to your claude_desktop_config.json file:

With Environment Variables

{
  "mcpServers": {
    "mcp-imap": {
      "command": "npx",
      "args": ["mcp-imap"],
      "env": {
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "IMAP_USERNAME": "[email protected]",
        "IMAP_PASSWORD": "your-app-password",
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_SECURE": "false",
        "SMTP_USERNAME": "[email protected]",
        "SMTP_PASSWORD": "your-app-password",
        "MCP_DEBUG": "false",
        "IMAP_IGNORE_TLS": "false",
        "IMAP_REJECT_UNAUTHORIZED": "true"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "mcp-imap": {
      "command": "node",
      "args": ["C:/path/to/mcp-imap/build/index.js"],
      "env": {
        "IMAP_HOST": "your-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "IMAP_USERNAME": "[email protected]",
        "IMAP_PASSWORD": "your-password",
        "SMTP_HOST": "your-server.com",
        "SMTP_PORT": "587",
        "SMTP_SECURE": "false",
        "SMTP_USERNAME": "[email protected]",
        "SMTP_PASSWORD": "your-password",
        "MCP_DEBUG": "false"
      }
    }
  }
}

For Self-Signed Certificates

{
  "mcpServers": {
    "mcp-imap": {
      "command": "npx",
      "args": ["mcp-imap"],
      "env": {
        "IMAP_HOST": "mail.yourcompany.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "IMAP_USERNAME": "[email protected]",
        "IMAP_PASSWORD": "your-password",
        "IMAP_IGNORE_TLS": "true",
        "IMAP_REJECT_UNAUTHORIZED": "false"
      }
    }
  }
}

Other MCP Clients (Chatbox, etc.)

Use the same environment variable structure as shown above. The server supports universal MCP client compatibility.

Environment Variables

Required IMAP Variables

• IMAP_HOST: IMAP server hostname
• IMAP_USERNAME: Email username
• IMAP_PASSWORD: Email password or app password

Optional IMAP Variables (with defaults)

• IMAP_PORT: IMAP server port (default: "993")
• IMAP_SECURE: Use SSL connection (default: "true")
• IMAP_IGNORE_TLS: Ignore TLS certificate errors (default: "true")
• IMAP_REJECT_UNAUTHORIZED: Reject unauthorized certificates (default: "false")

SMTP Variables (Optional - uses IMAP as fallback)

• SMTP_HOST: SMTP server hostname (fallback: IMAP_HOST)
• SMTP_PORT: SMTP server port (fallback: auto-detect from IMAP port)
• SMTP_USERNAME: SMTP username (fallback: IMAP_USERNAME)
• SMTP_PASSWORD: SMTP password (fallback: IMAP_PASSWORD)
• SMTP_SECURE: Use SSL connection (fallback: auto-detect)
• SMTP_IGNORE_TLS: Ignore TLS certificate errors (fallback: IMAP_IGNORE_TLS)
• SMTP_REJECT_UNAUTHORIZED: Reject unauthorized certificates (fallback: IMAP_REJECT_UNAUTHORIZED)

Debug Variables

• MCP_DEBUG: Enable debug logging (default: "false")

Usage Examples

The server automatically uses environment variables configured in your MCP client. You can directly use the tools:

1. List folders:

   list_folders

2. Read last 3 emails:

   read_emails with limit=3

3. Read unseen emails:

   read_emails with unseen=true, limit=5

4. Search emails from specific sender:

   search_emails with query="FROM [email protected]", limit=10

5. Search emails by date range:

   search_emails with query="SUBJECT report", dateFrom="2024-08-01", dateTo="2024-08-31"

6. Read a specific email:

   read_single_email with uid=12345, includeBody=true

7. Send an email:

   send_email with to="[email protected]", subject="Test", text="Hello World"

Performance Tips

1. Use appropriate limits: For broad searches, start with small limits
2. Date filters: Use date ranges to limit search scope
3. Specific folders: Search in specific folders instead of all folders
4. Specific criteria: Use FROM/SUBJECT instead of general text search
5. Read status: Use UNSEEN/SEEN for efficient filtering

Error Handling

The server provides professional error handling for:

• Invalid date formats
• Lost IMAP connections
• Invalid UIDs
• Non-existent folders
• Exceeded limits
• Certificate issues

Debug information is available when MCP_DEBUG=true.

License

MIT License

Security

• Never hardcode credentials in code
• Use environment variables for sensitive credentials
• Consider using app-specific passwords for Gmail
• The server handles secure connections automatically

Development

# Development mode
npm run dev

# Build
npm run build

# Run built version
npm start