Better Email MCP

email

mcp-name: io.github.n24q02m/better-email-mcp

IMAP/SMTP email for AI agents -- read, send, organize, and manage attachments across accounts.

Sister projects from n24q02m (click to expand)

Table of contents

• Features
• Install
• CLI
• Smithery
• Documentation
• Tools
• Comparison
• Remote (HTTP Mode)
• Outlook OAuth Device Code (HTTP mode)
• Configuration
• Security
• Build from Source
• Trust Model
• License

Features

• Multi-account support -- manage 6+ email accounts (Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, custom IMAP)
• App Passwords -- no OAuth2 setup required for most providers; clone and run in 1 minute
• 4 composite tools (plus help) -- search, read, send, reply, forward, organize, and credential status in single calls
• Auto-discovery -- provider settings detected from email address, custom IMAP host supported
• Thread-aware -- reply/forward maintains In-Reply-To and References headers
• Tiered token optimization -- compressed descriptions + on-demand help tool + MCP Resources

Install

The server runs in two modes: stdio (default, single-user, credentials from env vars) and HTTP (opt-in, single-user with a bearer token). For stdio, add it to your MCP client config:

{

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

The package is @n24q02m/email (formerly @n24q02m/better-email-mcp; old package receives one final release then freezes). The MCP Registry id stays io.github.n24q02m/better-email-mcp, and the legacy better-email-mcp command is kept as an alias of email.

Multiple accounts are comma-separated: user1@gmail.com:pass1,user2@outlook.com:pass2. See Configuration for all env vars, and Remote (HTTP Mode) to run a hosted multi-user server.

Most providers use an App Password (no OAuth setup); Outlook/Hotmail/Live use a bundled OAuth device-code flow in HTTP mode. Settings (IMAP/SMTP host, port) are auto-discovered from the email domain.

Install matrix

Full per-client walkthroughs: docs.n24q02m.com/servers/email/setup/.

CLI

The package ships one binary, email (run via npx @n24q02m/email), also installed under its legacy name better-email-mcp. With no arguments it starts the MCP server over stdio; it also accepts one flag and one subcommand:

# stdio server (normally launched by your MCP client, not by hand)

EMAIL_CREDENTIALS="user@gmail.com:app-password" npx @n24q02m/email

HTTP multi-user server

npx @n24q02m/email --http

One-off Outlook OAuth device-code sign-in

npx @n24q02m/email auth user@outlook.com

Sign out of a single account (or omit the email to clear all)

npx @n24q02m/email logout user@outlook.com

auth/logout are only for Outlook/Hotmail/Live addresses -- other providers use an App Password in EMAIL_CREDENTIALS. See Remote (HTTP Mode) for the HTTP config.

Smithery

Published with a Smithery config (smithery.yaml). Smithery runs the server over stdio with no build config required; credentials come from the environment (see Configuration). The start command is:

startCommand:

type: stdio commandFunction: |- (config) => ({ command: 'npx', args: ['-y', '@n24q02m/email'] })

Documentation

Full docs at [docs.n24q02m.com/servers/email/](https://docs.n24q02m.com/servers/email/):

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json

Install with AI agent -- paste this to your AI coding agent:

Install MCP server email following the steps at

https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

Tools

Public tool rename

The public send tool is replaced by messages with action: new, reply, or forward. This follows the MCP N+2 standard: sending is an action in the messages domain, so keeping a separate send entry would duplicate that domain and add redundant tool-list and help-topic surface. The old name is removed directly; there is no compatibility alias.

MCP Resources

| email://docs/config | Credential setup and runtime config