MCP Mail Server

1.2.1 verified Sat Apr 25 auth: no javascript

An MCP (Model Context Protocol) server enabling AI assistants like Claude and Cursor to perform email operations via IMAP and SMTP. Current stable version is 1.2.1, maintained on GitHub with regular updates. Key differentiators: environment-based secure configuration, natural language commands for email tasks, automatic connection management, multi-mailbox support, attachment handling, and TLS/SSL compatibility. Designed for integration with AI agents that use the MCP protocol.

Common errors

error Error: connect ECONNREFUSED your-imap-server.com:993 ↓

cause IMAP server is not reachable, or the hostname/port is incorrect.

fix

Verify IMAP_HOST and IMAP_PORT. Ensure the server allows connections from your network. If using TLS, IMAP_SECURE should be 'true' and port 993.

error Error: Invalid search criteria: expected array of arrays ↓

cause Search criteria not provided in the correct nested array format required by the IMAP library.

fix

Wrap each search condition in its own array. For example: [['FROM', 'someone@example.com'], ['SINCE', '01-Jan-2025']].

error Error: getaddrinfo ENOTFOUND imap.example.com ↓

cause The IMAP hostname cannot be resolved via DNS.

fix

Double-check the IMAP_HOST environment variable. Ensure the hostname is correct and accessible from your environment.

error Error: No IMAP connection. Please ensure server is running. ↓

cause The IMAP connection was not established before calling a tool that requires it.

fix

Verify that environment variables are set correctly and the IMAP server is reachable. Restart the MCP server.

Warnings

breaking Search criteria (FROM/TO/SUBJECT/BODY/KEYWORD/SINCE) must use nested array format; previous single-array format causes errors. ↓

fix Update to version 1.2.1 or later, and ensure search criteria are provided as nested arrays.

breaking Email dates are now stored in ISO 8601 format instead of locale string; existing email date parsing may break. ↓

fix Update to 1.2.1. If you rely on date strings, parse ISO 8601 instead of locale-specific strings.

gotcha Environment variables must be set exactly as documented. Missing IMAP_HOST or SMTP_HOST will cause connection failures. ↓

fix Ensure all required env vars are present: IMAP_HOST, IMAP_PORT, IMAP_SECURE, SMTP_HOST, SMTP_PORT, SMTP_SECURE, EMAIL_USER, EMAIL_PASS.

deprecated The getRecentMessages() tool previously used the IMAP RECENT flag, which is unreliable. Now it fetches latest N messages by UID. ↓

fix Update to 1.2.1. The tool now behaves correctly; no code changes needed, but behavior differs.

gotcha The reply_to_email tool may write literal "undefined" into the body when the text parameter is empty string. ↓

fix Update to 1.2.1. Ensure you always provide a non-empty text parameter.

gotcha Ensure IMAP_PORT and SMTP_PORT are strings, not numbers, when setting environment variables (e.g., '993' not 993). ↓

fix Use string values for ports in the env object.

Install

npm install mcp-mail-server

yarn add mcp-mail-server

pnpm add mcp-mail-server

Imports

MailServer
wrong
```
const MailServer = require('mcp-mail-server')
```
correct
```
import { MailServer } from 'mcp-mail-server'
```
This package is an MCP server binary, not a library. It is executed as a command via npx.

Quickstart

Installs the MCP Mail Server globally and configures it as an MCP server for Claude Desktop with environment variables for IMAP and SMTP settings.

npm install -g mcp-mail-server
# Then add to claude_desktop_config.json:
{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "user@example.com",
        "EMAIL_PASS": "replace-with-password"
      }
    }
  }
}