Better Email MCP

What n24q02m/better-email-mcp does

n24q02m/better-email-mcp exposes email operations to MCP-compatible AI clients over IMAP and SMTP. It can search and read messages, organize mail, compose and send messages, reply within a thread, and forward email. It also provides mailbox-folder operations, attachment listing and downloading, credential-management actions, and on-demand tool documentation.

The server is designed for multiple accounts in one configuration. Supported provider families include Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, and custom IMAP services. Provider connection details can be inferred from the email domain, while custom IMAP hosts are supported for services that are not auto-discovered.

How it works

The default transport is stdio, intended for launching from an MCP client. HTTP mode is also available with bearer-token protection and is started explicitly with the package's HTTP option or transport setting. The package provides an email command; the legacy better-email-mcp command remains available as an alias.

Most accounts use an app password rather than an OAuth setup. Outlook, Hotmail, and Live accounts can use the bundled OAuth2 device-code flow when the server runs in HTTP mode. OAuth tokens are stored locally for that flow and can be cleared with the logout command.

Replies and forwards preserve thread-related In-Reply-To and References headers. Tool descriptions are kept compact, with more detail available through the help tool and MCP resources.

Setup and configuration

Install and run the package through the latest npm tag:

npx --yes @n24q02m/email@latest

For stdio, configure the MCP client to launch that command and provide credentials through EMAIL_CREDENTIALS:

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/email@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "user@gmail.com:app-password"
      }
    }
  }
}

Multiple accounts use comma-separated email:password pairs. An alternative is to set EMAIL_USER and EMAIL_APP_PASSWORD. Start HTTP mode with npx @n24q02m/email --http; it is intended for a single user and uses a bearer token. The command also supports Outlook authentication through email auth and token removal through email logout.

Tools and capabilities

• Search, read, organize, compose, send, reply to, and forward email through the messages functionality.
• List mailbox folders or inspect targeted IMAP STATUS metadata.
• List and download message attachments.
• Check credential status, obtain setup guidance, reset configuration, re-resolve provider settings, and clear cached data.
• Retrieve detailed documentation for any tool through the help functionality.
• Work with more than one configured email account.

Limitations and notes

Authentication is centered on app passwords for most providers, so the selected account must support that method. Outlook, Hotmail, and Live use the documented device-code path only in HTTP mode. Stdio is single-user and reads credentials from the process environment; HTTP mode is also described as single-user, despite the project documentation referring to hosted multi-user deployment separately.

The package is published as @n24q02m/email, while the MCP Registry identifier remains io.github.n24q02m/better-email-mcp. The project is licensed under Apache-2.0.