IMAP/SMTP email for AI agents -- read, send, organize, and manage attachments across accounts.
This Model Context Protocol (MCP) server provides IMAP/SMTP email capabilities for AI agents. It supports reading and sending email, organizing folders, and managing attachments. The server is designed for multi-account operation and includes auto-discovery, using composite tools.
๐ ๏ธ Key Features
IMAP/SMTP support
Read email for AI agents
Send email
Organize folders
Manage attachments
Multi-account support
Auto-discovery
Composite tools
๐ Use Cases
Automated agent workflows that need to read and respond to messages
Email triage by organizing folders
Sending emails with attachment handling across multiple accounts
Configuring accounts via auto-discovery rather than manual setup
โก Developer Benefits
MCP integration for email tooling
TypeScript ecosystem alignment (repo topic)
Container-friendly approach (docker topic)
Clear focus on IMAP/SMTP, folders, and attachments
โ ๏ธ Limitations
No additional limitations are stated in the provided data.
The server runs in two modes: stdio (default, single-user, credentials from env vars) and HTTP (opt-in: one shared bearer token, or several users with separate mailboxes from a users.toml token table). For stdio, add it to your MCP client config:
The package is @n24q02m/email (formerly @n24q02m/better-email-mcp; old package
receives one final release then freezes). The MCP Registry id is
io.github.n24q02m/email; the entry published earlier as
io.github.n24q02m/better-email-mcp stays frozen under that old name, because
registry versions are immutable. 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, or listed in an accounts file. See Configuration for all env vars, and Remote (HTTP Mode) to run a hosted 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
Client
Install
Claude Code
/plugin marketplace add n24q02m/claude-plugins + /plugin install email@n24q02m-plugins (stdio; prompts for EMAIL_CREDENTIALS), or an mcpServers entry in .mcp.json / client settings
Codex CLI
[mcp_servers.email] block in ~/.codex/config.toml (stdio command/args or HTTP type/url)
OpenCode
mcpServers block in opencode.json
Cursor / Windsurf / Gemini CLI / any MCP client
mcpServers JSON in the client's config โ same shape as the example above
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. Every MCP tool is also a subcommand, so the same handlers run with or without an MCP client.
Server and operator commands
Invocation
Description
email
Start the MCP server over stdio (default). Reads credentials from EMAIL_CREDENTIALS, or from EMAIL_USER + EMAIL_APP_PASSWORD
email --http
Start the server in HTTP mode (auth chosen by MCP_AUTH_MODE, see Remote (HTTP Mode)). Equivalent to MCP_TRANSPORT=http or TRANSPORT_MODE=http
Authenticate an Outlook/Hotmail/Live account via OAuth2 Device Code flow. Tokens are saved to ~/.email/tokens.json, or with --user to that HTTP multi-user namespace (~/.email/users/<namespace>/tokens.json). The outlook provider positional is optional (email has a single OAuth2 provider); --client-id overrides OUTLOOK_CLIENT_ID for a self-hosted Azure AD app
email logout [<email>] [--user=<namespace>]
Clear the locally stored Outlook token(s), of one multi-user namespace with --user. Omit <email> to clear every stored token
email config status / email status
Report whether a stored credential file exists (never prints credential values)
email config delete --yes
Delete the stored credential file
email doctor
Node, credential backend, store-directory, and session checks
Tool commands
Each tool keeps its MCP name and actions; its JSON-Schema properties become --flags, so the CLI cannot accept an argument the tool does not take. Output is human-readable text, or the tool's exact JSON envelope with --json. A failure prints one message to stderr and exits 1.
config-tool is the MCP config tool; the bare email config command stays the operator command for the stored credential file (its status/delete actions predate the tool surface). email --help lists tool commands and operator commands as separate groups, and email <command> --help prints that command's actions and flags.
bash
# stdio server (normally launched by your MCP client, not by hand)
EMAIL_CREDENTIALS="user@gmail.com:app-password" npx @n24q02m/email
# HTTP server, several users with separate mailboxes (see Remote (HTTP Mode))
MCP_AUTH_MODE=multi 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
# Search, read, and organize mail through the same handlers the MCP tools use
npx @n24q02m/email messages search --query UNREAD --limit 5 --json
npx @n24q02m/email messages read --uid 4211 --preview --max_chars 800
npx @n24q02m/email messages mark_read --uids 12,13,14
npx @n24q02m/email folders list --account user@gmail.com
# Attachments and credential state
npx @n24q02m/email attachments list --account user@gmail.com --uid 42 --json
npx @n24q02m/email config-tool status --json
# Per-command actions and flags come from the tool schema
npx @n24q02m/email messages --help
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:
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.
Old public name
New public name
Reason
Alias removal
send
messages (action: new | reply | forward)
N+2 domain-tool rule: outbound mail is part of the messages mega-tool, not a second action-level tool.
Removed directly in the Unreleased release; no alias
anyone holding the one shared token (MCP_AUTH_TOKEN_HASH)
the server-wide accounts (accounts file, env vars, email auth outlook)
multi
each user in a hullusers.toml token table (MCP_USERS_FILE)
only that user's own namespace: users/<namespace>/accounts.toml and users/<namespace>/tokens.json under the data directory
no-auth (or unset, no hash, loopback bind)
anything that can reach the loopback port
the server-wide accounts
A request with no token or a wrong one gets 401. With no mode and no hash the server refuses to start on a non-loopback bind.
Self-Hosting (HTTP Mode)
Shared-token mode: one principal. Accounts come from an accounts file, the env vars, or email auth outlook <address>. The account mode (single/multi) applies here too: with several accounts, a single-target tool requires account, and a fan-out read still returns the healthy accounts when one fails.
bash
export MCP_AUTH_TOKEN_HASH='scrypt$...'# required: the container binds 0.0.0.0 and refuses to start without authexport EMAIL_CREDENTIALS='you@gmail.com:app-password'
docker run -p 8080:8080 \
-e PORT=8080 \
-e MCP_AUTH_TOKEN_HASH \
-e EMAIL_CREDENTIALS \
-e HOME=/data \
-v email-data:/data \
n24q02m/email:latest
Mint the hash with printf '%s' "$TOKEN" | email token hash; the token is read from stdin, never argv. Clients send the raw token as Authorization: Bearer <token>. Saved Outlook tokens live under /data/.email/ and persist when the /data volume is kept. EMAIL_MCP_TOKEN_HASH is the older name of MCP_AUTH_TOKEN_HASH and still works.
Self-Hosting for several users (multi mode)
Each user gets their own bearer token and their own mailboxes; no user can see another's, and the server-wide accounts (EMAIL_ACCOUNTS_FILE, EMAIL_CREDENTIALS, EMAIL_USER) are not served to anyone in this mode. Provisioning is host-side:
Then give each namespace its mailboxes under the data directory, in the accounts file schema:
bash
# <data dir>/users/alice/accounts.toml (in Docker: /data/.email/users/alice/accounts.toml)# and/or an Outlook grant for one namespace:
email auth outlook alice@outlook.com --user alice
MCP_AUTH_MODE=multi MCP_USERS_FILE=/data/users.toml email --http
Accounts are re-read on every tool call, so an edited accounts.toml applies without a restart. A namespace is one path segment (letters, digits, _, -). The config tool reports a caller's own accounts; setup_reset and setup_complete are refused for a multi-user caller.
Self-Hosting with Docker Compose
The repository ships docker-compose.http.yml, which builds the http image target and
publishes it on host loopback only (127.0.0.1:8082):
bash
export MCP_AUTH_TOKEN_HASH='scrypt$...'# required; see the note aboveexport EMAIL_CREDENTIALS='you@gmail.com:app-password'
docker compose -f docker-compose.http.yml up
The server is then reachable at http://localhost:8082. To serve other machines, put your own TLS reverse proxy on the same host in front of the loopback port. Prebuilt multi-arch images are published to Docker Hub (n24q02m/email)
and GHCR (ghcr.io/n24q02m/email).
Outlook OAuth Device Code
Outlook/Hotmail/Live accounts use OAuth2 device-code. Run email auth outlook <address> once. On first use:
The CLI prints a device code and a Microsoft login URL
Open the URL in a browser and enter the code
Sign in and authorize the app
Tokens are saved to ~/.email/tokens.json (created with mode 0600 on POSIX). In Docker that path is /data/.email/tokens.json. A token file from an earlier release (~/.better-email-mcp/tokens.json) is copied forward on the next start; the old file is left in place.
OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure registration needed.
In stdio mode, Outlook accounts use an App Password instead (Outlook Account Settings โ Security โ Advanced security options โ App passwords).
Configuration
To trust mise configuration automatically, set trusted_config_paths in the user-level config at ~/.config/mise/config.toml; do not add it to this project's .mise.toml.
Variable
Required
Default
Description
EMAIL_ACCOUNTS_FILE
Alternative (stdio)
~/.email/accounts.toml when it exists
Path to the accounts file. off, none, false or 0 disables file lookup entirely. When a file is found it wins over EMAIL_CREDENTIALS and EMAIL_USER
EMAIL_CREDENTIALS
Alternative (stdio)
-
Email credentials, email:app-password per account, comma-separated for multi-account. Optional custom IMAP host/port: email:password:imap_host:imap_port
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
EMAIL_APP_PASSWORD
Alternative (stdio, single-account)
-
App password (Gmail/Yahoo/iCloud) or Outlook App Password; used with EMAIL_USER
EMAIL_DATA_DIR
No
$HOME
Base directory for this server's own files. Saved Outlook tokens live in <dir>/.email/tokens.json, so the default is ~/.email/tokens.json (the Docker image sets HOME=/data); a file an earlier release wrote under <dir>/.better-email-mcp/ is copied forward on startup. A relative value is resolved under $HOME and must stay inside it; use an absolute path to point at a mounted volume
PORT
No
0 (OS-assigned)
Server port (http mode); set explicitly (e.g. 8080) to bind a fixed port
HOST
No
-
Bind address (http mode)
MCP_AUTH_MODE
No (http)
-
token, multi or no-auth. Unset: a token hash selects token; without one HTTP runs unauthenticated only on loopback and refuses any other bind
MCP_AUTH_TOKEN_HASH
No (http token; required when not bound to loopback)
-
scrypt hash of the shared bearer token, minted with email token hash. EMAIL_MCP_TOKEN_HASH is the older name and still works
MCP_RPM
No (http token)
-
Per-minute request cap for the shared token
MCP_USERS_FILE
No (http multi)
~/.hull/users.toml
users.toml token table: one [users.<id>] row per user with token_hash, namespace, optional enabled and [users.<id>.limits] rpm
EMAIL_MCP_DRAFT_ONLY
No
-
Set to 1 for agents that read untrusted mail: every new/reply/forward is saved to the account's Drafts folder instead of being sent (as if called with draft: true), and move/archive/trash/setup_reset are removed from the tool list (and refused if called anyway). Search, read and flag changes still work
OUTLOOK_CLIENT_ID
No
d56f8c71-9f7c-43f4-9934-be29cb6e77b0 (bundled public client)
Override the bundled Azure AD public client for self-hosted Outlook OAuth2 (or --client-id=<id> on auth, which overrides this env var)
OUTLOOK_EMAIL
No
-
Workaround when Microsoft device-code response omits the email field
OUTLOOK_TENANT
No
consumers (stdio/CLI), common (http device-code)
Microsoft directory to sign in against, used for both the device-code and the token-refresh endpoint. Set common for a work/school (Entra ID) mailbox, or a tenant GUID / verified domain to pin one directory
Space-separated scope list. Narrow it (e.g. drop SMTP.Send) for a read-only deployment โ a grant consented with fewer scopes cannot be refreshed against the full list
OUTLOOK_EXTRA_DOMAINS
No
-
Comma-separated domains routed to OAuth in addition to outlook.com/hotmail.com/live.com. Needed for a Microsoft 365 mailbox on your own domain, which otherwise looks like a password account
Account modes
Whatever the credential source, the server runs in one of two account modes, and
reports which one is active:
Mode
When
Behaviour
single
exactly one enabled account
Every tool uses that account. account may be omitted, and is used to name it when given
multi
two or more enabled accounts
Read tools (folders list, messages search, messages read) fan out over every enabled account. A tool that acts on one mailbox (send, reply, forward, move, trash, attachments) requires account; omitting it is rejected with the list of accounts to choose from instead of guessing
config status returns mode (single, multi, or none when nothing is
configured or every row is disabled), accounts with the enabled addresses, and
disabled_accounts when the accounts file opts a row out.
Isolation guarantee. In multi mode one failing account never hides the
others: a fan-out read that fails for one account (wrong password, IMAP connect
error, missing or expired OAuth token) still returns every other account's
results, and the failed entry carries its own account_id/account_email and
error message. A single-target action is only rejected when the account is
genuinely ambiguous, and the rejection names the accounts.
Accounts file (single and multi account)
For a deployment that keeps its mailboxes in a file rather than a comma-separated
env var, point EMAIL_ACCOUNTS_FILE at a TOML file (the same shape hull uses for
its users.toml):
toml
[accounts.personal]email = "me@gmail.com"password = "app-password"[accounts.work]email = "me@company.com"password = "app-password"imap_host = "imap.company.com"# optional; skips provider auto-discoveryimap_port = 993# optional, default 993 with a custom hostsmtp_host = "smtp.company.com"# optional, default: guessed from imap_hostsmtp_port = 587# optionalsmtp_security = "starttls"# optional: tls | ssl | starttls | nonealiases = ["team@company.com"] # optional; other addresses this mailbox may send asenabled = true# optional; false keeps the row but skips it
When EMAIL_ACCOUNTS_FILE is unset, ~/.email/accounts.toml is used if it
exists (relative paths resolve against $HOME; the directory is
$EMAIL_DATA_DIR/.email/ when EMAIL_DATA_DIR is set). Set
EMAIL_ACCOUNTS_FILE=off (or none/false/0) to disable file lookup and use
the env vars only. A file that is selected explicitly and cannot be read is a
boot error rather than a silent fallback.
Validation is strict, so a typo cannot degrade into "no accounts configured":
unknown keys, a duplicate mailbox, an empty file, a file with no
[accounts.<id>] table, and a row whose IMAP/SMTP cannot be resolved are all
errors that name the file (and the offending account id).
Many mailboxes receive mail for more than one address: iCloud+ custom email
domains, Gmail "Send mail as" addresses, Fastmail or Zoho aliases. List them as
aliases on the account, and messagesnew/reply/forward can send as any
of them with from:
For more than a couple of mailboxes, prefer the accounts file:
it carries per-account host/port/security settings and can disable a row without
deleting it.
Custom IMAP Host
bash
# Custom hostname (default port 993, implicit TLS)
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com
# Custom hostname with a custom port
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com:1993
# Local IMAP proxy -- "localhost" is accepted as a host, even without a dot
EMAIL_CREDENTIALS=user@custom.com:password:localhost:1993
Each account can use its own host and port. A non-993 port is treated as
plaintext/STARTTLS -- the usual shape for a local IMAP proxy (for example
email-oauth2-proxy).
Microsoft 365 work/school accounts
A mailbox in a Microsoft 365 organisation -- including one on your own domain --
signs in through Entra ID rather than the consumer directory, and Microsoft
disabled basic auth for Exchange Online in 2024, so an App Password is not an
option. Two settings make it work:
bash
# Sign in against the directory that owns the mailbox
OUTLOOK_TENANT=common # or a tenant GUID / verified domain# Route your own domain to OAuth instead of asking for a password
OUTLOOK_EXTRA_DOMAINS=company.com
OUTLOOK_TENANT applies to the token refresh as well as the initial sign-in --
refreshing a work/school token against the consumer directory fails with
AADSTS7000012: The grant was obtained for a different tenant.
If the mailbox was consented with a narrower grant (say IMAP but no SMTP), match
it with OUTLOOK_SCOPES so the refresh does not ask for more than was granted.
Search Query Language
Query
Description
UNREAD
Unread emails
FLAGGED
Starred emails
SINCE 2024-01-01
Emails after date
FROM boss@company.com
Emails from sender
SUBJECT meeting
Emails matching subject
UNREAD SINCE 2024-06-01
Compound filter
Supported Providers
Provider
Auth
Save-to-Sent
Gmail
App Password
Auto (skipped)
Yahoo
App Password
Auto (skipped)
iCloud/Me.com
App-Specific Password
Auto (skipped)
Outlook/Hotmail/Live
OAuth2 (Device Code)
IMAP APPEND
Zoho
App Password
IMAP APPEND
ProtonMail
ProtonMail Bridge
IMAP APPEND
Custom
Via email:pass:imap.host
IMAP APPEND
Security
Credential sanitization -- Passwords never leaked in error messages
App Passwords -- Uses app-specific passwords, not regular passwords
Token storage -- Outlook OAuth tokens are written with mode 0600 on POSIX (not enforced on Windows)
IMAP validation -- Search queries validated before execution
Build from Source
bash
git clone https://github.com/n24q02m/email.git
cd email
bun install
bun run dev
Trust Model
Whoever runs the server (or your OS user for stdio) can read every credential it stores. In HTTP multi mode each caller reaches only its own namespace, but the operator still holds all of them. Storage depends on the deployment mode:
Mode
Storage
Encryption
Who can read your data?
HTTP (Docker)
Env vars (EMAIL_CREDENTIALS) and saved Outlook tokens in $HOME/.email/tokens.json (the /data volume)
Tokens: plain JSON, POSIX file mode 0600
Server operator
HTTP multi
Per user: $HOME/.email/users/<namespace>/accounts.toml and tokens.json (the /data volume)
Plain files, POSIX file mode 0600 for tokens
Server operator; each caller sees only its own namespace
stdio
Env vars; saved Outlook tokens in ~/.email/tokens.json; legacy config.enc from earlier releases is still read