better-email-mcp — Claude Code MCP server: install guide
better-email-mcp connects AI agents to email via IMAP and SMTP to read inboxes, reply inside existing threads, and organize folders.
Apache-2.0 ★ 38 updated 2026-10-27
claude mcp add better-email-mcp -e EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> -- npx -y @n24q02m/emailWhat better-email-mcp 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.
What it helps with
- 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 for the agent
- 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 [email protected] from my primary address
How to install better-email-mcp
Platform CLI
claude mcp add better-email-mcp -e EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> -- npx -y @n24q02m/emailReplace <…> with your own values
Platform CLI
codex mcp add n24q02m-better-email-mcp --env EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> -- npx -y @n24q02m/emailReplace <…> with your own values
Config file
{
"mcpServers": {
"n24q02m-better-email-mcp": {
"command": "npx",
"args": [
"-y",
"@n24q02m/email"
],
"env": {
"EMAIL_CREDENTIALS": "<EMAIL_CREDENTIALS>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"n24q02m-better-email-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@n24q02m/email"
],
"env": {
"EMAIL_CREDENTIALS": "<EMAIL_CREDENTIALS>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> n24q02m-better-email-mcp npx -y @n24q02m/emailReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about better-email-mcp
How do I install better-email-mcp in Claude Code?
Run claude mcp add better-email-mcp -e EMAIL_CREDENTIALS=<EMAIL_CREDENTIALS> -- npx -y @n24q02m/email with your credentials filled in.
What does better-email-mcp do?
It gives the agent tools to inspect inboxes, dispatch emails, search archives, and manage folders via IMAP and SMTP.
Is OAuth2 required to connect an email account?
Most supported mail providers only require a generated app password supplied through the EMAIL_CREDENTIALS variable.