# better-email-mcp

better-email-mcp connects AI agents to email via IMAP and SMTP to read inboxes, reply inside existing threads, and organize folders.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 38 repo stars
- Author: n24q02m
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/n24q02m/email
- Updated: 2026-10-27
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/n24q02m-better-email-mcp

## What it does

This server integrates IMAP and SMTP inboxes directly into coding assistants. It handles services like Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, and custom mail servers. The package supplies 4 composite tools covering 23 separate actions for searching, reading, sending, and reorganizing messages. Inbound thread headers such as `In-Reply-To` and `References` are preserved on replies, preventing fragmented conversations.

The runtime defaults to `stdio` mode and runs through `npx` using the `@n24q02m/email` package. Most email providers authenticate with an app-specific password instead of an OAuth2 flow. Pass account details into the `EMAIL_CREDENTIALS` environment variable as `email:password`, using commas to separate multiple accounts. Connecting an inbox fails immediately if you do not generate an app password in your email provider first.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `EMAIL_CREDENTIALS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add better-email-mcp -e EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> -- npx -y @n24q02m/email
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add n24q02m-better-email-mcp --env EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> -- npx -y @n24q02m/email
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "n24q02m-better-email-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@n24q02m/email"
            ],
            "env": {
                "EMAIL_CREDENTIALS": "<EMAIL_CREDENTIALS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "n24q02m-better-email-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@n24q02m/email"
            ],
            "env": {
                "EMAIL_CREDENTIALS": "<EMAIL_CREDENTIALS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> n24q02m-better-email-mcp npx -y @n24q02m/email
```
Replace <…> with your own values

## When to use it
- read incoming messages and run inbox searches through the agent
- reply to emails while preserving conversation thread headers
- organize and move messages between email folders
- send outbound emails using standard IMAP and SMTP credentials

## Example prompts
- Check my inbox for the latest message from billing and summarize it
- Reply to the release thread confirming that deployment finished
- Send the status update to client@example.com from my primary address

## Similar
- [email-mcp](https://affpapa.org/en/nevibecode/mcp/email-mcp.md) — MCP server · ★ 161 repo stars
- [Email (IMAP/SMTP)](https://affpapa.org/en/nevibecode/mcp/email-imapsmtp.md) — MCP server · ★ 14 repo stars
- [email-smtp-imap-mcp](https://affpapa.org/en/nevibecode/mcp/email-smtp-imap-mcp.md) — MCP server · ★ 25 repo stars
- [email-smtp-send](https://affpapa.org/en/nevibecode/skills/email-smtp-send.md) — skill · 6800 installs
- [email-security-auditor-cpp](https://affpapa.org/en/nevibecode/skills/email-security-auditor-cpp.md) — skill · 484 installs
- [WireCat Mail](https://affpapa.org/en/nevibecode/mcp/wirecat-mail.md) — MCP server · ★ 3 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
