imap-mail-mcp

An MCP (Model Context Protocol) server that lets Claude read, search, and send email over standard IMAP/SMTP. Works with any provider that supports username/password authentication over IMAP and SMTP — IONOS, GMX, Web.de, and most other non-Gmail/non-Microsoft providers.

Tools

Tool	Description
list_mailboxes	List all folders (INBOX, Sent, Drafts, Trash, custom folders, ...)
list_messages	List the most recent messages in a mailbox
search_messages	Search by sender, recipient, subject, body text, or date range
get_message	Fetch the full text/HTML body and attachment metadata of one message
mark_message	Mark a message as read/unread or flagged/unflagged
send_mail	Send a new email or reply to an existing one

Setup

1. Install dependencies and build:

   npm install
   npm run build
   

2. Copy .env.example to .env and fill in your mailbox credentials (only needed for local testing via npm start — see below for how credentials are supplied when running through Claude Desktop).

3. If your provider supports 2FA / app-specific passwords, use one of those instead of your main account password.

Using it with Claude Desktop

Add an entry to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "imap-mail": {
      "command": "node",
      "args": ["/absolute/path/to/imap-mail-mcp/dist/index.js"],
      "env": {
        "EMAIL_USER": "you@example.com",
        "EMAIL_PASSWORD": "your-password-or-app-password",
        "IMAP_HOST": "imap.example.com",
        "IMAP_PORT": "993",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "587"
      }
    }
  }
}

Restart Claude Desktop fully (quit and reopen) after editing the config.

Environment variables

Variable	Required	Default	Notes
EMAIL_USER	yes	—	Mailbox login (usually your email address)
EMAIL_PASSWORD	yes	—	Password or app-specific password
IMAP_HOST	yes	—	e.g. imap.ionos.de
IMAP_PORT	no	993	IMAP over implicit TLS
SMTP_HOST	yes	—	e.g. smtp.ionos.de
SMTP_PORT	no	587	STARTTLS; use 465 for implicit TLS

For backwards compatibility, IONOS_EMAIL, IONOS_PASSWORD, IONOS_IMAP_HOST, IONOS_IMAP_PORT, IONOS_SMTP_HOST, and IONOS_SMTP_PORT are also accepted as aliases.

Security notes

• Credentials are only ever read from environment variables. They are never logged, written to disk, or included in any response text beyond what the IMAP/SMTP server itself returns.
• Claude Desktop's mcpServers config stores the env block in plain text on your machine. Anyone with access to your user account can read it, same as any other locally saved password.
• .env is git-ignored — never commit real credentials.

Requirements

• Node.js 18+