# better-email-mcp

Connects email accounts via IMAP and SMTP to AI agents. Useful when you need to read incoming mail, reply within threads, and manage attachments directly in your agent workspace.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 35
- 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-11
- HTML: https://affpapa.org/en/nevibecode/mcp/better-email-mcp

## What it does

The server links your coding agent to email providers over IMAP and SMTP. It provides 4 composite tools with 23 distinct actions for reading messages, sending replies, organizing mailboxes, and searching. Provider parameters for services like Gmail, iCloud, and Yahoo resolve automatically from the address domain.

Setup relies on app-specific passwords rather than regular account passwords. Because standard web passwords fail security checks for direct IMAP access, you must generate an app password and feed it via the `EMAIL_CREDENTIALS` variable. Separate multiple inboxes with commas.

Execution runs in standard input-output mode by default, alongside an opt-in HTTP setup with OAuth 2.1. Outgoing replies and forwards retain message threading by preserving In-Reply-To and References headers.

## 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/better-email-mcp
```
Replace <…> with your own values

### Codex

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

### Cursor

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

### GitHub Copilot

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

### Gemini CLI

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

## When to use it
- inspect mailboxes and read unread messages across accounts
- send thread-aware email replies with proper message headers
- connect several email providers using a single credentials string
- search message history and handle file attachments from the prompt

## Example prompts
- Check unread emails in user@gmail.com received today.
- Reply to the latest message in this thread and keep the conversation headers intact.
- Search the inbox for invoices sent last month and list the attachments.

## Similar
- [Reactive Resume](https://affpapa.org/en/nevibecode/mcp/reactive-resume.md) — MCP server · ★ 44874
- [screenpipe](https://affpapa.org/en/nevibecode/mcp/screenpipe.md) — MCP server · ★ 22053
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12791
- [kaneo](https://affpapa.org/en/nevibecode/mcp/kaneo.md) — MCP server · ★ 9602
- [Mindwtr](https://affpapa.org/en/nevibecode/mcp/mindwtr.md) — MCP server · ★ 2318
- [Azure DevOps (ADO)](https://affpapa.org/en/nevibecode/mcp/azure-devops-ado.md) — MCP server · ★ 2067

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