# n24q02m/better-email-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/n24q02m/better-email-mcp  
**GitHub Stars:** 35  
**npm Downloads (last month):** 1393  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/n24q02m-better-email-mcp

## Description
IMAP/SMTP email MCP server with App Passwords (no OAuth2). Auto-discovers Gmail, Outlook, Yahoo, iCloud. 5 composite tools: search, read, send, reply, forward. Multi-account support.

## Tools
Capabilities this server exposes over MCP:

- **messages** — Search, read, organize, compose, reply to, and forward emails
- **folders** — List mailbox folders or read targeted IMAP STATUS metadata
- **attachments** — List and download email attachments
- **config** — Credential status and setup guidance, reset, re-resolve, cache clear
- **help** — Get full documentation for any tool

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "better-email-mcp": {
    "command": "npx",
    "args": ["-y","@n24q02m/email"],
    "env": {
      "EMAIL_CREDENTIALS": "",
      "EMAIL_USER": "",
      "EMAIL_APP_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `EMAIL_CREDENTIALS`, `EMAIL_USER`, `EMAIL_APP_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
npx --yes @n24q02m/email@latest
```

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

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/n24q02m-better-email-mcp/readme_