emperor-mail

emperor-mail

Your mailbox as MCP tools: search and read by default; draft and send only when you switch them on.

emperor-mail is an MCP server that reads and writes email over IMAP and SMTP, so an agent can find a message, read it and its attachments (PDF, Word, Excel and OpenDocument spreadsheets included), and draft a reply for you to send.

• Built on emperor-mcp: stateless Streamable HTTP, framed tool output, forwarded credentials, compact tool definitions (Emperor Profile P1.1).
• Two ways to run: one mailbox (credentials in the environment, stdio or HTTP) or a shared server (each request brings its own credentials in headers; nothing is stored).
• Read-only by default. Started with no switch, the server lists only its four reading tools. --writable adds draft; --allow-send adds send (and draft), and even then send writes only to the recipients you list. Sent mail is copied to your Sent folder.
• Markdown bodies go out as text/plain plus rendered text/html.
• Password, app password or OAuth 2.0 (XOAUTH2, for Gmail and Microsoft 365).
• Single binary, pure Rust: IMAP via async-imap, parsing via mail-parser, SMTP via lettre, PDF text via lopdf, spreadsheets via calamine, Markdown via pulldown-cmark, TLS via rustls and the operating system's trust store.

Install

Prebuilt binaries (macOS arm64/x86_64, Linux x86_64, Windows x86_64) are attached to GitHub releases. From source:

cargo install emperor-mail

Or as a container (stdio, one mailbox from the environment):

docker build -t emperor-mail https://github.com/yarenty/emperor-mail.git

docker run -i --rm -e MAIL_USER -e MAIL_PASSWORD -e IMAP_HOST -e SMTP_HOST emperor-mail

The image runs emperor-mail serve --stdio, so writing is switched on with variables rather than flags: add -e MAIL_WRITABLE=true for draft, or -e MAIL_ALLOW_SEND=true -e MAIL_SEND_ALLOW=@example.org for draft and send to that domain (see Flags).

Run for one mailbox

Credentials come from the environment. Use an app password, never your account password (see Provider notes).

export MAIL_USER="you@example.com"

export MAIL_PASSWORD=" " export IMAP_HOST="imap.example.com" # port 993, implicit TLS by default export SMTP_HOST="smtp.example.com" # only needed for send; port 465 by default

emperor-mail doctor # check everything before you connect a client emperor-mail serve --stdio # read-only, for desktop clients that spawn the server emperor-mail serve --stdio --writable # also draft replies into the Drafts folder emperor-mail serve # or Streamable HTTP on 127.0.0.1:8033/mcp

plain (no encryption) is accepted only from the environment and only for a loopback host, such as a local mail bridge. Certificates are always verified against the operating system's trust store.

Flags

serve and doctor take the same flags.

The write switches can also come from the environment, for containers and catalogs that cannot pass flags: MAIL_WRITABLE for --writable and MAIL_ALLOW_SEND for --allow-send (unset, empty, false, 0, no or off mean off; true, 1, yes or on mean on; anything else stops the server at start-up), MAIL_SEND_ALLOW for --send-allow and MAIL_FROM_ALLOW for --from-allow (comma-separated; empty means no pattern). A flag on the command line wins over its variable. The safety rule is the same either way: with sending on and no recipient pattern, every recipient is refused, and patterns without sending on are a start-up error.

Run as a shared server

On a shared server every request carries the caller's own credentials in headers. They are used for that one tool call and dropped with the request: never stored, never logged.

emperor-mail serve --bind 127.0.0.1:8033              # read-only

emperor-mail serve --bind 127.0.0.1:8033 --writable # callers may also save drafts

These ten names are the only headers the server captures.

Rules:

• The login is one source. If a request carries any of X-Mail-User, X-Mail-Password or X-Mail-Oauth-Token, the whole login comes from headers: the user plus exactly one of password and token. A header user is never combined with a secret from the environment.
• Servers follow the login. A caller with its own login may name its own servers in X-Mail-Imap-* / X-Mail-Smtp-*; what it leaves out falls back to the environment (IMAP_HOST, SMTP_HOST, ...). With a login from the environment, server headers are ignored, so the operator's password never goes to a host a caller picked.
• No plaintext from headers. A server named in a header is reached over TLS or STARTTLS only; plain is refused.
• `--pin-servers` makes the environment's servers win for every caller (a company server that should only ever reach imap.corp.example).
• When the mail server rejects the credentials, the HTTP response is `401` with a JSON-RPC error (code -32040), so a client can ask the user to sign in again.
• Put the server behind an ingress that terminates TLS and authenticates callers; the headers carry passwords. Without one, keep it on 127.0.0.1.

Provider notes

• Gmail: turn on 2-Step Verification, then create an app password at https://myaccount.google.com/apppasswords. IMAP_HOST=imap.gmail.com, SMTP_HOST=smtp.gmail.com. IMAP must be enabled in Gmail settings for some accounts. Gmail files sent mail in "[Gmail]/Sent Mail" by itself: run with --no-sent-copy to avoid a second copy.
• Fastmail: create an app password under Settings → Privacy & Security → Integrations → App passwords, with IMAP and SMTP access. IMAP_HOST=imap.fastmail.com, SMTP_HOST=smtp.fastmail.com.
• Outlook / Microsoft 365 accounts require OAuth: see below. Exchange Online files sent mail by itself; use --no-sent-copy.

OAuth (Gmail, Microsoft 365)

emperor-mail speaks SASL XOAUTH2 on IMAP and SMTP. It does not run an OAuth flow and holds no client secret: the client obtains and refreshes the access token and passes it per request in X-Mail-Oauth-Token (or MAIL_OAUTH_TOKEN for stdio), with the mailbox address in X-Mail-User / MAIL_USER. The token is forwarded for that one call and never stored or logged. An expired token gives a 401, the cue for the client to refresh it.

• Gmail: scope https://mail.google.com/; IMAP_HOST=imap.gmail.com, SMTP_HOST=smtp.gmail.com.
• Microsoft 365: scopes https://outlook.office.com/IMAP.AccessAsUser.All and https://outlook.office.com/SMTP.Send (plus offline_access for refresh); IMAP_HOST=outlook.office365.com, SMTP_HOST=smtp.office365.com, SMTP_PORT=587. SMTP AUTH must be enabled for the mailbox.

Other servers: if yours offers only STARTTLS, set IMAP_PORT=143 / SMTP_PORT=587 (the security mode follows the port) or set *_SECURITY=starttls explicitly.

Connect a client

Claude Desktop (claude_desktop_config.json), one mailbox over stdio:

{

"mcpServers": { "mail": { "command": "emperor-mail", "args": ["serve", "--stdio"], "env": { "MAIL_USER": "you@example.com", "MAIL_PASSWORD": " ", "IMAP_HOST": "imap.example.com", "MAIL_WRITABLE": "true" } } } }

Claude Code, stdio or HTTP:

claude mcp add mail -e MAIL_USER=you@example.com -e MAIL_PASSWORD='<app password>' \

-e IMAP_HOST=imap.example.com -- emperor-mail serve --stdio

or against a running HTTP server, credentials in headers

claude mcp add --transport http mail http://127.0.0.1:8033/mcp \ --header "X-Mail-User: you@example.com" --header "X-Mail-Password: " \ --header "X-Mail-Imap-Host: imap.example.com"

kowalski (config.toml):

[[mcp.servers]]

name = "mail" transport = "http" url = "http://127.0.0.1:8033/mcp" headers = { "X-Mail-User" = "you@example.com", "X-Mail-Password" = " ", "X-Mail-Imap-Host" = "imap.example.com" }

or one mailbox over stdio: MAIL_USER, MAIL_PASSWORD, IMAP_HOST and the other

variables are read from kowalski's environment

[[mcp.servers]] name = "mail" transport = "stdio"

--writable lists draft (replies saved in Drafts); leave it out for