{"id":45653533,"url":"https://github.com/n24q02m/better-email-mcp","last_synced_at":"2026-07-02T05:01:17.544Z","repository":{"id":340278985,"uuid":"1165314516","full_name":"n24q02m/better-email-mcp","owner":"n24q02m","description":"IMAP/SMTP email for AI agents -- read, send, organize folders, and manage attachments across multiple accounts, with auto-discovery.","archived":false,"fork":false,"pushed_at":"2026-07-01T04:35:31.000Z","size":1807,"stargazers_count":23,"open_issues_count":1,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T05:24:10.413Z","etag":null,"topics":["ai-agents","ai-coding","claude","claude-code","cursor","docker","email","imap","mcp","mcp-server","model-context-protocol","open-source","smtp","typescript"],"latest_commit_sha":null,"homepage":"https://mcp.n24q02m.com/servers/better-email-mcp/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n24q02m.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-24T03:22:43.000Z","updated_at":"2026-07-01T04:35:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/n24q02m/better-email-mcp","commit_stats":null,"previous_names":["n24q02m/better-email-mcp"],"tags_count":108,"template":false,"template_full_name":null,"purl":"pkg:github/n24q02m/better-email-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-email-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-email-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-email-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-email-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n24q02m","download_url":"https://codeload.github.com/n24q02m/better-email-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n24q02m%2Fbetter-email-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35031039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","claude","claude-code","cursor","docker","email","imap","mcp","mcp-server","model-context-protocol","open-source","smtp","typescript"],"created_at":"2026-02-24T07:21:00.335Z","updated_at":"2026-07-02T05:01:17.531Z","avatar_url":"https://github.com/n24q02m.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Better Email MCP\n\nmcp-name: io.github.n24q02m/better-email-mcp\n\n**IMAP/SMTP email for AI agents -- read, send, organize folders, and manage attachments across multiple accounts, with auto-discovery.**\n\n\u003c!-- Badge Row 1: Status --\u003e\n[![CI](https://github.com/n24q02m/better-email-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/better-email-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/n24q02m/better-email-mcp/graph/badge.svg?token=O2GWBWCZGF)](https://codecov.io/gh/n24q02m/better-email-mcp)\n[![npm](https://img.shields.io/npm/v/@n24q02m/better-email-mcp?logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/@n24q02m/better-email-mcp)\n[![Docker](https://img.shields.io/docker/v/n24q02m/better-email-mcp?label=docker\u0026logo=docker\u0026logoColor=white\u0026sort=semver)](https://hub.docker.com/r/n24q02m/better-email-mcp)\n[![License: MIT](https://img.shields.io/github/license/n24q02m/better-email-mcp)](LICENSE)\n\n\u003c!-- Badge Row 2: Tech --\u003e\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript\u0026logoColor=white)](#)\n[![Node.js](https://img.shields.io/badge/Node.js-5FA04E?logo=nodedotjs\u0026logoColor=white)](#)\n[![IMAP/SMTP](https://img.shields.io/badge/IMAP%2FSMTP-005FF9?logo=maildotru\u0026logoColor=white)](#)\n[![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release\u0026logoColor=white)](https://github.com/python-semantic-release/python-semantic-release)\n[![Renovate](https://img.shields.io/badge/renovate-enabled-1A1F6C?logo=renovatebot\u0026logoColor=white)](https://developer.mend.io/)\n\n\u003c!-- BEGIN: AUTO-GENERATED-CROSS-PROMO --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eSister projects from n24q02m\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n| Project | Tagline | Tag |\n|---|---|---|\n| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |\n| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |\n| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |\n| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |\n| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |\n| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |\n| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |\n| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |\n| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |\n| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |\n| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |\n| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |\n| [tacet](https://github.com/n24q02m/tacet) | TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn... | Tooling |\n| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |\n| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |\n\n\u003c/details\u003e\n\u003c!-- END: AUTO-GENERATED-CROSS-PROMO --\u003e\n\n## Table of contents\n\n- [Features](#features)\n- [Install](#install)\n- [Documentation](#documentation)\n- [Tools](#tools)\n- [Comparison](#comparison)\n- [Remote (HTTP Mode)](#remote-http-mode)\n- [Outlook OAuth Device Code (HTTP mode)](#outlook-oauth-device-code-http-mode)\n- [Configuration](#configuration)\n- [Security](#security)\n- [Build from Source](#build-from-source)\n- [Trust Model](#trust-model)\n- [License](#license)\n\n\n\n\u003ca href=\"https://glama.ai/mcp/servers/n24q02m/better-email-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/n24q02m/better-email-mcp/badge\" alt=\"Better Email MCP server\" /\u003e\n\u003c/a\u003e\n\n## Features\n\n- **Multi-account support** -- manage 6+ email accounts (Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, custom IMAP)\n- **App Passwords** -- no OAuth2 setup required for most providers; clone and run in 1 minute\n- **5 composite tools** with 21 actions (plus `help` + `config__open_relay`) -- search, read, send, reply, forward, organize, and credential setup in single calls\n- **Auto-discovery** -- provider settings detected from email address, custom IMAP host supported\n- **Thread-aware** -- reply/forward maintains In-Reply-To and References headers\n- **Tiered token optimization** -- compressed descriptions + on-demand `help` tool + MCP Resources\n\n## Install\n\nThe server runs in two modes: **stdio** (default, single-user, credentials from env vars) and **HTTP** (opt-in, multi-user with OAuth 2.1). For stdio, add it to your MCP client config:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"better-email\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"@n24q02m/better-email-mcp@latest\"],\n      \"env\": {\n        \"EMAIL_CREDENTIALS\": \"user@gmail.com:app-password\"\n      }\n    }\n  }\n}\n```\n\nMultiple accounts are comma-separated: `user1@gmail.com:pass1,user2@outlook.com:pass2`. See [Configuration](#configuration) for all env vars, and [Remote (HTTP Mode)](#remote-http-mode) to run a hosted multi-user server.\n\nMost 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.\n\n## Documentation\n\nFull docs at **[mcp.n24q02m.com/servers/better-email-mcp/setup/](https://mcp.n24q02m.com/servers/better-email-mcp/setup/)**:\n\n- [Setup](https://mcp.n24q02m.com/servers/better-email-mcp/setup/) -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json\n- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio (default) and HTTP (opt-in, multi-user with OAuth 2.1)\n- [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- per-JWT-sub credential model\n\n**Install with AI agent** -- paste this to your AI coding agent:\n\n\u003e Install MCP server `better-email-mcp` following the steps at\n\u003e https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md\n\n## Tools\n\n| Tool | Actions | Description |\n|:-----|:--------|:------------|\n| `messages` | `search`, `read`, `mark_read`, `mark_unread`, `flag`, `unflag`, `move`, `archive`, `trash` | Search, read, and organize emails |\n| `folders` | `list` | List mailbox folders |\n| `attachments` | `list`, `download` | List and download email attachments |\n| `send` | `new`, `reply`, `forward` | Compose, reply, and forward emails |\n| `config` | `status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear` | Credential setup via browser relay, status check, reset, re-resolve, cache clear |\n| `config__open_relay` | - | Open the relay configuration form in the browser and return the relay URL |\n| `help` | - | Get full documentation for any tool |\n\n### MCP Resources\n\n| URI | Description |\n|:----|:------------|\n| `email://docs/messages` | Message operations reference |\n| `email://docs/folders` | Folder operations reference |\n| `email://docs/attachments` | Attachment operations reference |\n| `email://docs/send` | Send/compose reference |\n| `email://docs/config` | Credential setup and runtime configuration reference |\n| `email://docs/help` | Full documentation |\n\n## Comparison\n\nHow better-email-mcp stacks up against direct competitors in each pillar:\n\n| Capability | better-email-mcp | [email-mcp](https://github.com/codefuturist/email-mcp) | [Gmail-MCP-Server](https://github.com/GongRzhe/Gmail-MCP-Server) | [mcp-mail-server](https://github.com/yunfeizhu/mcp-mail-server) |\n|---|---|---|---|---|\n| IMAP/SMTP (provider-agnostic) | Yes | Yes | No (Gmail API only) | Yes |\n| Multi-account | Yes (comma-separated creds) | Yes | No (single global credential) | No (single account per instance) |\n| App Passwords | Yes (no OAuth setup) | Yes | No (OAuth2 only) | Yes |\n| Auto-discovery from email address | Yes | Yes (8 providers) | n/a (Gmail only) | No (manual host/port) |\n| Bundled Outlook OAuth (no user Azure app) | Yes (device-code, Thunderbird-pattern client) | partial (OAuth2 XOAUTH2, experimental) | No (user-supplied Google OAuth) | No |\n| Attachments (list + download) | Yes | Yes | Yes | Yes |\n| HTTP multi-user mode (per-JWT-sub) | Yes (OAuth 2.1, self-hostable) | No (stdio only) | No (stdio only) | No (stdio only) |\n\n## Remote (HTTP Mode)\n\nRun as a multi-user HTTP server with OAuth 2.1 authentication:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"better-email\": {\n      \"type\": \"http\",\n      \"url\": \"https://email.n24q02m.com/mcp\"\n    }\n  }\n}\n```\n\n### Self-Hosting (HTTP Mode)\n\nSingle multi-user mode (relay form for App-Password providers + bundled Outlook OAuth device-code):\n\n```bash\ndocker run -p 8080:8080 \\\n  -e PORT=8080 \\\n  -e PUBLIC_URL=https://your-domain.com \\\n  n24q02m/better-email-mcp:latest\n```\n\nUsers provide their own email credentials through the OAuth flow / paste form. No server-side `EMAIL_CREDENTIALS` needed. With the default Docker self-host, per-user credentials are held in an in-memory store (cleared on restart); users re-submit after a restart. Outlook OAuth uses the bundled public Azure client (`d56f8c71-9f7c-43f4-9934-be29cb6e77b0`, Thunderbird-pattern) -- no user-side Azure app registration needed.\n\n### Cloudflare serverless mode (KV-only)\n\nDeploy a per-user serverless instance at `https://email.n24q02m.com`: each JWT `sub`\ngets its own Container Durable Object, and all credentials AND Outlook OAuth tokens are\nAES-256-GCM encrypted into Workers KV (one `subs/\u003csub\u003e/config` blob per user) so they\n**survive scale-to-zero / container recreate with no re-auth**. The JWT signing key is\nderived deterministically from `CREDENTIAL_SECRET` (EdDSA), so the user's identity is\nstable across recreate. Required secrets: `CREDENTIAL_SECRET` (per-sub vault + EdDSA),\n`MCP_RELAY_PASSWORD` (form gate), `MCP_DCR_SERVER_SECRET` (intentional multi-user\ndeploy). See `wrangler.jsonc`.\n\n\u003e Keying Outlook tokens by JWT `sub` (in the per-sub KV blob) resolves the former\n\u003e email-keyed `tokens.json` ambiguity (CLAUDE.md Known Bug #4): two users' Outlook\n\u003e accounts can no longer collide.\n\n\u003e Caveat: `localhost` IMAP accounts (`email:pass:localhost:1993`) are valid for\n\u003e local / VM deployments but CANNOT work on Cloudflare — there is no co-located IMAP\n\u003e proxy inside the container. Use a publicly-reachable IMAP host on CF.\n\n## Outlook OAuth Device Code (HTTP mode)\n\nIn HTTP mode, Outlook/Hotmail/Live accounts use OAuth2 device-code automatically. On first use:\n\n1. The server prints a device code and a Microsoft login URL\n2. Open the URL in a browser and enter the code\n3. Sign in and authorize the app\n4. Tokens are persisted per JWT sub — in the encrypted Cloudflare KV credential blob (`subs/\u003csub\u003e/config`) on the serverless deploy, or in `~/.better-email-mcp/tokens.json` for single-user / stdio\n\nOAuth uses the bundled public Azure client (`d56f8c71-9f7c-43f4-9934-be29cb6e77b0`, Thunderbird-pattern) -- no user-side Azure registration needed.\n\nIn **stdio mode**, Outlook accounts use an **App Password** instead (Outlook Account Settings → Security → Advanced security options → App passwords).\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|:---------|:---------|:--------|:------------|\n| `EMAIL_CREDENTIALS` | Yes (stdio) | - | Email credentials, `email:app-password` per account, comma-separated for multi-account. Optional custom IMAP host/port: `email:password:imap_host:imap_port` |\n| `EMAIL_USER` | Alternative (stdio, single-account) | - | Email address. Used with `EMAIL_APP_PASSWORD` as a per-field alternative to `EMAIL_CREDENTIALS`; merged into `EMAIL_CREDENTIALS` at boot |\n| `EMAIL_APP_PASSWORD` | Alternative (stdio, single-account) | - | App password (Gmail/Yahoo/iCloud) or Outlook App Password; used with `EMAIL_USER` |\n| `PUBLIC_URL` | No (http) | - | Server's public URL for relay / OAuth redirect links |\n| `PORT` | No | `0` (OS-assigned) | Server port (http mode); set explicitly (e.g. `8080`) to bind a fixed port |\n| `HOST` | No | - | Bind address (http mode) |\n| `MCP_AUTH_DISABLE` | No (http) | - | Set to `1` to skip Bearer JWT verification when behind an external auth gateway |\n| `OUTLOOK_CLIENT_ID` | No | `d56f8c71-9f7c-43f4-9934-be29cb6e77b0` (bundled public client) | Override the bundled Azure AD public client for self-hosted Outlook OAuth2 |\n| `OUTLOOK_EMAIL` | No | - | Workaround when Microsoft device-code response omits the email field |\n\n### Multiple Accounts\n\n```bash\nEMAIL_CREDENTIALS=user1@gmail.com:pass1,user2@outlook.com:pass2,user3@yahoo.com:pass3\n```\n\n### Custom IMAP Host\n\n```bash\n# Custom hostname (default port 993, implicit TLS)\nEMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com\n\n# Custom hostname with a custom port\nEMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com:1993\n\n# Local IMAP proxy -- \"localhost\" is accepted as a host, even without a dot\nEMAIL_CREDENTIALS=user@custom.com:password:localhost:1993\n```\n\nEach account can use its own host and port. A non-993 port is treated as\nplaintext/STARTTLS -- the usual shape for a local IMAP proxy (for example\n[email-oauth2-proxy](https://github.com/simonrob/email-oauth2-proxy)).\n\n### Search Query Language\n\n| Query | Description |\n|:------|:------------|\n| `UNREAD` | Unread emails |\n| `FLAGGED` | Starred emails |\n| `SINCE 2024-01-01` | Emails after date |\n| `FROM boss@company.com` | Emails from sender |\n| `SUBJECT meeting` | Emails matching subject |\n| `UNREAD SINCE 2024-06-01` | Compound filter |\n\n### Supported Providers\n\n| Provider | Auth | Save-to-Sent |\n|:---------|:-----|:-------------|\n| Gmail | App Password | Auto (skipped) |\n| Yahoo | App Password | Auto (skipped) |\n| iCloud/Me.com | App-Specific Password | Auto (skipped) |\n| Outlook/Hotmail/Live | OAuth2 (Device Code) | IMAP APPEND |\n| Zoho | App Password | IMAP APPEND |\n| ProtonMail | ProtonMail Bridge | IMAP APPEND |\n| Custom | Via `email:pass:imap.host` | IMAP APPEND |\n\n## Security\n\n- **Credential sanitization** -- Passwords never leaked in error messages\n- **App Passwords** -- Uses app-specific passwords, not regular passwords\n- **Token storage** -- Outlook OAuth tokens saved with 600 permissions\n- **IMAP validation** -- Search queries validated before execution\n\n## Build from Source\n\n```bash\ngit clone https://github.com/n24q02m/better-email-mcp.git\ncd better-email-mcp\nbun install\nbun run dev\n```\n\n## Trust Model\n\nThis plugin implements **TC-NearZK** (in-memory, ephemeral). See the [mcp-core trust model](https://mcp.n24q02m.com/servers/mcp-core/trust-model/) for full classification.\n\n| Mode | Storage | Encryption | Who can read your data? |\n|---|---|---|---|\n| HTTP remote (hosted) | In-memory `Map\u003csub, OAuthToken\u003e` | In-process only | Server process (cleared on restart) |\n| HTTP self-host | Same as hosted | Same | Only you (admin = user) |\n| stdio | platformdirs `mcp` config dir (`config.enc`; e.g. `%APPDATA%\\mcp\\Config\\config.enc` on Windows) | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |\n\n## License\n\nMIT -- See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn24q02m%2Fbetter-email-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn24q02m%2Fbetter-email-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn24q02m%2Fbetter-email-mcp/lists"}