Skip to content
Back to search

mail-mcp

Secure IMAP/SMTP/EWS/Graph API MCP server in Rust — Microsoft 365, Hotmail, Gmail, Zoho, OAuth2, multi-account

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tecnologicachile/mail-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tecnologicachile/mail-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tecnologicachile--mail-mcp/badge.svg)](/listings/tecnologicachile--mail-mcp)

HTML

<a href="/listings/tecnologicachile--mail-mcp"><img src="/api/listings/tecnologicachile--mail-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Copy and paste this prompt into Claude Code and it will install, compile, and configure everything for you:

Install and configure the mail-mcp MCP server from https://github.com/tecnologicachile/mail-mcp

1. Clone the repo, build with cargo build --release
2. Add the MCP server to .claude.json with the binary path
3. For Microsoft accounts: use EWS (simplest) — run device code flow with
   client_id d3590ed6-52b3-4102-aeff-aad2292ab01c and scope
   https://outlook.office365.com/EWS.AccessAsUser.All offline_access
   Then configure MAIL_EWS_<ID>_USER and MAIL_EWS_<ID>_REFRESH_TOKEN
4. For Gmail: configure MAIL_IMAP + MAIL_SMTP with App Password from
   https://myaccount.google.com/apppasswords
5. For Zoho: configure MAIL_IMAP + MAIL_SMTP with standard password
6. Enable write/send: MAIL_IMAP_WRITE_ENABLED=true, MAIL_SMTP_WRITE_ENABLED=true

My email accounts to configure:
- <your-email@example.com>

Replace the last line with your email(s). Claude Code will guide you through each step including the OAuth2 device code flow for Microsoft accounts.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 995 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <h1 align="center">mail-mcp</h1>
  3. <p align="center">
  4. <strong>Production-ready email MCP server for AI agents</strong><br>
  5. IMAP + SMTP + EWS + Microsoft Graph API — built in Rust
  6. </p>
  7. <p align="center">
  8. <a href="https://github.com/tecnologicachile/mail-mcp/releases"><img src="https://img.shields.io/github/v/release/tecnologicachile/mail-mcp?label=release" alt="Release"></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/github/license/tecnologicachile/mail-mcp" alt="License"></a>
  10. <a href="https://github.com/tecnologicachile/mail-mcp/stargazers"><img src="https://img.shields.io/github/stars/tecnologicachile/mail-mcp?style=social" alt="Stars"></a>
  11. </p>
  12. </p>
  13. ---
  14. Most email MCP servers only do IMAP reads. This one does **everything**: read, search, send, reply, forward, bulk operations, Microsoft Graph API, and Exchange Web Services — with real OAuth2, multi-account, and multi-provider support. Written in Rust for speed and safety.
  15. ## What's New
  16. - **Guided account configuration:** `mail-mcp config init` and `mail-mcp accounts add`
  17. store accounts in `~/.mail-mcp/config.toml`, outside the MCP client's JSON.
  18. List, edit, remove, and run read-only connection tests from the CLI.
  19. [Start with guided setup](docs/account-setup.md#guided-setup-with-toml).
  20. ## What's New in v0.6.2
  21. - **Faster searches.** `imap_search_messages` and `imap_search_all_mailboxes`
  22. now fetch the headers of a whole result page with one `UID FETCH` instead
  23. of one per message. On high-latency servers a 50-message page went from
  24. 20-40 s to 3-9 s, and searching every mailbox is about twice as fast.
  25. Results are unchanged.
  26. ([#44](https://github.com/tecnologicachile/mail-mcp/pull/44), by tdabasinskas)
  27. - **MCP tool annotations.** Every tool now declares `readOnlyHint`,
  28. `destructiveHint`, `idempotentHint` and `openWorldHint`. Clients that use
  29. them can run the 14 read-only tools without asking each time. Sends,
  30. moves and other changes are marked as writes, and deletes, flag changes,
  31. `draft_update` and `draft_send` as destructive.
  32. ([#43](https://github.com/tecnologicachile/mail-mcp/pull/43), by tdabasinskas)
  33. ## What's New in v0.6.1
  34. - **Message content stays out of the logs at `RUST_LOG=info`.** At that
  35. level the rmcp library logged every JSON-RPC response in full, which with
  36. the HTTP transport put message subjects and bodies in the server log (the
  37. journal, for a systemd service). When `RUST_LOG` sets a global level of
  38. `info` or more verbose, rmcp is now capped at `warn` unless `RUST_LOG`
  39. names it (for example `RUST_LOG=info,rmcp=info` while debugging). The
  40. stdio transport did not log responses, and with `RUST_LOG` unset nothing
  41. changes. If you run v0.6.0 or earlier over HTTP, set
  42. `RUST_LOG=info,rmcp=warn`.
  43. - **EWS setup scope fixed.** Microsoft now rejects
  44. `https://outlook.office365.com/EWS.AccessAsUser.All` with `AADSTS70011`
  45. (`invalid_scope`). The Quickstart uses
  46. `https://outlook.office.com/EWS.AccessAsUser.All`. Existing EWS tokens keep
  47. working; this only matters when getting a new one.
  48. ## What's New in v0.6.0
  49. Nothing changes for an existing install unless you opt in.
  50. - **Self-update for shell and PowerShell installs.** The installers now also
  51. install `mail-mcp-update`; run it to move to the latest release in place.
  52. Homebrew installs keep updating with `brew upgrade`.
  53. - **Rotated OAuth2 refresh tokens are used, and can be persisted.** Microsoft
  54. returns a new refresh token on every refresh; the server used to discard
  55. it and keep refreshing with the configured one until that one expired. It
  56. now refreshes with the newest token. Set `MAIL_OAUTH2_TOKEN_STORE` to a file
  57. path to also keep it across restarts (written `0600`, never fatal if it
  58. cannot be written). Changing the refresh token in your config always wins
  59. over a stored one.
  60. - **Send rules in tool and field descriptions.** The preview-and-confirm rule
  61. and the "`body_text` and `body_html` are separate fields" rule now also
  62. appear on the send tools and body fields, for MCP gateways that do not
  63. forward the server instructions. See
  64. [Running behind an MCP gateway](docs/advanced-configuration.md#running-behind-an-mcp-gateway)
  65. for what else changes when mail-mcp sits behind a gateway.
  66. ## What's New in v0.5.0
  67. - **New: draft tools** (`draft_create`, `draft_update`, `draft_send`,
  68. `draft_delete`, `draft_list`) closing
  69. [#3](https://github.com/tecnologicachile/mail-mcp/issues/3) and
  70. [#17](https://github.com/tecnologicachile/mail-mcp/issues/17). An agent can
  71. save a message in the account's own Drafts folder, revise it, and send it
  72. later, so a person can review it in their mail client first. The same five
  73. tools work on every backend: IMAP + SMTP, Exchange Web Services and
  74. Microsoft Graph, picked per account (EWS config, else Graph config, else
  75. IMAP). `list_all_accounts` reports the backend as `drafts_with`.
  76. - **Separate gate: `MAIL_DRAFTS_ENABLED`** (default `false`). It is
  77. independent of `MAIL_IMAP_WRITE_ENABLED`: every operation on an existing
  78. `draft_id` first checks that the target really is a draft (IMAP Drafts
  79. folder, EWS `IsDraft`, Graph `isDraft`), so enabling drafts never grants
  80. move or delete on other mail. `draft_send` also requires
  81. `MAIL_SMTP_WRITE_ENABLED`.
  82. - **Graph accounts need the `Mail.ReadWrite` scope** for drafts; see
  83. [account setup](docs/account-setup.md). The EWS attachment flow
  84. (`CreateItem` with `SaveOnly`, then `CreateAttachment`) follows the approach
  85. proposed by [@verdelyi](https://github.com/verdelyi) in
  86. [#14](https://github.com/tecnologicachile/mail-mcp/pull/14).
  87. - **Fix: SMTP messages now carry a Message-ID on the sender's domain**
  88. ([#7](https://github.com/tecnologicachile/mail-mcp/issues/7)). Before, lettre
  89. sent no Message-ID of its own, so the id returned by the send tools was
  90. empty and the Sent copy had none.
  91. - Verified live on IMAP (Zoho) and Microsoft Graph; the EWS draft path is
  92. covered by unit tests.
  93. ## What's New in v0.4.17
  94. - **New: `imap_search_all_mailboxes`** by
  95. [@tdabasinskas](https://github.com/tdabasinskas) in
  96. [#35](https://github.com/tecnologicachile/mail-mcp/pull/35). Runs one search
  97. in every selectable mailbox of an account and returns the newest matches,
  98. each labelled with its mailbox. Built for providers without an "All Mail"
  99. folder (iCloud), where one conversation is spread over INBOX, Sent Messages
  100. and project folders. The work is spread over `MAIL_IMAP_SEARCH_CONCURRENCY`
  101. connections (default `4`, clamped to `1..=8`); a mailbox that fails is
  102. reported and does not abort the search. Scope it with `include_mailboxes` /
  103. `exclude_mailboxes`.
  104. - **Thread search by Message-ID** by
  105. [@tdabasinskas](https://github.com/tdabasinskas) in
  106. [#34](https://github.com/tecnologicachile/mail-mcp/pull/34).
  107. `imap_search_messages` takes a new `thread_message_id` criterion that
  108. matches a message and every message whose `In-Reply-To` or `References`
  109. carries it, so an agent can pull a whole conversation in one search.
  110. ## What's New in v0.4.16
  111. - **`imap_list_mailboxes` cap is now configurable and visible** by
  112. [@tdabasinskas](https://github.com/tdabasinskas) in
  113. [#33](https://github.com/tecnologicachile/mail-mcp/pull/33). The tool used to
  114. silently drop everything past 200 mailboxes — on accounts with more folders
  115. (e.g. 217 on iCloud), folders like `Sent Messages` simply never appeared.
  116. The cap is now set with `MAIL_IMAP_MAX_MAILBOXES` (default `200`, clamped to
  117. `1..=10000`), and the response carries two additive fields, `total` and
  118. `truncated`, so clients can always tell a capped list from a complete one.
  119. Nothing changes unless the variable is set.
  120. ## What's New in v0.4.15
  121. - **New: opt-in streamable HTTP transport** by
  122. [@tdabasinskas](https://github.com/tdabasinskas) in
  123. [#32](https://github.com/tecnologicachile/mail-mcp/pull/32). Set
  124. `MAIL_MCP_TRANSPORT=http` to serve MCP streamable HTTP (stateless) instead
  125. of stdio — useful for running the server on another machine behind an MCP
  126. gateway. Binds to `127.0.0.1:8000` at `/mcp` by default, configurable via
  127. `MAIL_MCP_HTTP_HOST` / `MAIL_MCP_HTTP_PORT` / `MAIL_MCP_HTTP_PATH`, with
  128. graceful shutdown on SIGINT/SIGTERM. **The endpoint has no built-in
  129. authentication** — keep it on loopback or behind an authenticating gateway;
  130. see `docs/advanced-configuration.md#remote-http-transport`. stdio remains
  131. the default: nothing changes unless the variable is set.
  132. ## What's New in v0.4.14
  133. Community release — both changes came from external contributors. Thank you!
  134. - **New: `MAIL_ATTACHMENT_UPLOAD_DIR` — confine outbound `file_path`
  135. attachments** by [@mjones-PL](https://github.com/mjones-PL) in
  136. [#31](https://github.com/tecnologicachile/mail-mcp/pull/31), closing
  137. [#11](https://github.com/tecnologicachile/mail-mcp/issues/11). Without a
  138. restriction, send tools would read any file the server process can access —
  139. a prompt-injected model could exfiltrate SSH keys or `.env` files as
  140. attachments. Set this variable to a directory and every `file_path` is
  141. canonicalized (`..` and symlinks resolved) and must land inside it; missing
  142. and out-of-scope files return the same error so the check cannot probe for
  143. file existence. Opt-in: when unset, behavior is unchanged. See
  144. `docs/security.md#outbound-attachment-scope`.
  145. - **Fixed: `FROM_EMAIL` validation no longer rejects dotless internal hosts**
  146. by [@arwack](https://github.com/arwack) in
  147. [#30](https://github.com/tecnologicachile/mail-mcp/pull/30). Addresses the
  148. v0.4.13 upgrade caveat: `noreply@localhost` / `alerts@intranet` style
  149. addresses on corporate internal relays are accepted again, while the real
  150. typo checks (multiple `@`, whitespace, empty local part) remain. If you held
  151. the v0.4.13 upgrade because of this, v0.4.14 is safe.
  152. ## What's New in v0.4.13
  153. - **`effective_from()` helper + `FROM_EMAIL` startup validation** by
  154. [@arwack](https://github.com/arwack) in
  155. [#29](https://github.com/tecnologicachile/mail-mcp/pull/29) — the follow-up
  156. to their #19. The `from_email` → `user` fallback now lives in one place
  157. (`SmtpAccountConfig::effective_from()`), and `MAIL_SMTP_<ID>_FROM_EMAIL` is
  158. validated when the server starts instead of failing on the first send.
  159. - **Behavior change — read before upgrading:** a malformed `FROM_EMAIL`
  160. (multiple `@`, whitespace, empty local part, or a domain without a dot) now
  161. prevents the server from starting, for **all** accounts. Note that dotless
  162. domains such as `user@localhost` or `alerts@intranet` are currently rejected
  163. too; if you use an internal relay address like that, hold the upgrade — a
  164. follow-up relaxing the dot rule is under discussion in #29.
  165. - Hardened APPEND wire-format tests by
  166. [@tordable](https://github.com/tordable) in
  167. [#28](https://github.com/tecnologicachile/mail-mcp/pull/28): mailbox
  168. quoting, announced literal length, and byte-for-byte payload are now
  169. asserted for every append test.
  170. ## What's New in v0.4.12
  171. Community release — both changes came from external contributors. Thank you!
  172. - **iCloud mailbox aliases + reads no longer mark messages as read** by
  173. [@felipefdl](https://github.com/felipefdl) in
  174. [#16](https://github.com/tecnologicachile/mail-mcp/pull/16). Short mailbox
  175. names now resolve to each provider's real folder (`Sent` → `Sent Messages`
  176. on iCloud / `[Gmail]/Sent Mail` on Gmail, `Trash` → `Deleted Messages`, and
  177. so on, multi-language) in search, copy, and move. Raw message fetches now use
  178. `BODY.PEEK[]`, so reading a message through the MCP no longer sets `\Seen`
  179. as a side effect — with a `BODY[]` fallback for servers that reject `PEEK`
  180. (the deprecated `RFC822` item, removed in #23, stays out). Validated against
  181. a real iCloud mailbox by the author; includes alias-resolution tests and
  182. iCloud setup docs.
  183. - **Optimized multi-stage Dockerfile + docker-compose** by
  184. [@monssefbaakka](https://github.com/monssefbaakka) in
  185. [#5](https://github.com/tecnologicachile/mail-mcp/pull/5). cargo-chef layer
  186. caching, TARGETARCH-aware musl cross-builds (amd64/arm64), and a `scratch`
  187. runtime image — 16.9 MB, down from 25.5 MB — verified to respond to MCP
  188. initialize/tools-list over stdio. The toolchain pin was bumped to
  189. Rust 1.90 (the codebase's let-chains require >= 1.88).
  190. ## What's New in v0.4.11
  191. Community bugfix release — both fixes came from external contributors. Thank you!
  192. - **Fixed: save-to-Sent silently failed on strict IMAP servers (iCloud and
  193. others)** by [@dominikknafelj](https://github.com/dominikknafelj) in
  194. [#26](https://github.com/tecnologicachile/mail-mcp/pull/26), reported in
  195. [#25](https://github.com/tecnologicachile/mail-mcp/issues/25). The `\Seen`
  196. flag introduced in v0.4.10 was sent without the RFC 3501 parenthesized
  197. flag-list syntax (`APPEND "Sent" \Seen …` instead of `APPEND "Sent" (\Seen) …`),
  198. because `async-imap` interpolates the flags argument verbatim. Strict servers
  199. rejected the APPEND and the sent copy was lost — while the tool still reported
  200. `status: ok`. Flags are now normalized before hitting the wire, and
  201. `smtp_send_message` / `smtp_reply_message` / `smtp_forward_message` responses
  202. include a new `saved_to_sent` field (`true`/`false`, or `null` when saving is
  203. disabled) so callers can detect archival failures.
  204. [@tordable](https://github.com/tordable) diagnosed and fixed the same root
  205. cause concurrently in [#24](https://github.com/tecnologicachile/mail-mcp/pull/24).
  206. - **Fixed: message reads returned empty on iCloud** by
  207. [@tdabasinskas](https://github.com/tdabasinskas) in
  208. [#23](https://github.com/tecnologicachile/mail-mcp/pull/23). Raw message
  209. fetches used the deprecated `RFC822` item, which iCloud accepts but leaves
  210. unpopulated. Fetches now use the IMAP4rev1 `BODY[]` item — same `\Seen`
  211. semantics, works everywhere — with a mock-server regression test pinning the
  212. wire format.
  213. ## What's New in v0.4.10
  214. Community release — all three changes came from external contributors. Thank you!
  215. - **NetEase IMAP compatibility (126.com / 163.com / yeah.net)** by
  216. [@pep-27](https://github.com/pep-27) in
  217. [#21](https://github.com/tecnologicachile/mail-mcp/pull/21). NetEase servers
  218. reject mailbox access from clients that don't identify themselves. mail-mcp
  219. now sends the RFC 2971 `ID` command after authentication whenever the server
  220. advertises the `ID` capability. Includes mock-server regression tests and
  221. NetEase setup docs in `docs/account-setup.md`.
  222. - **`MAIL_SMTP_<ID>_FROM_EMAIL` — sender address override** by
  223. [@arwack](https://github.com/arwack) in
  224. [#19](https://github.com/tecnologicachile/mail-mcp/pull/19). For shared/group
  225. mailboxes where SMTP authenticates with a personal account but the From
  226. address should be the group address. Applies to send, reply (including
  227. reply-all self-address detection) and forward; falls back to `_USER` when
  228. unset.
  229. - **Sent-mail copies are now marked `\Seen`** by
  230. [@ray-of-darkness](https://github.com/ray-of-darkness) in
  231. [#9](https://github.com/tecnologicachile/mail-mcp/pull/9). Copies the MCP
  232. appends to the Sent folder after SMTP send no longer show up as unread.
  233. ## What's New in v0.4.9
  234. - **New tool `imap_get_attachment` — download a single attachment to disk.**
  235. Until now the only ways to reach attachment bytes were `imap_get_message`
  236. (which returns attachment *metadata* and optional extracted PDF *text*, never
  237. the binary) and `imap_get_message_raw` (capped at 1 MB and base64-encoded
  238. into the response). A 7 MB email with X-ray images could not be retrieved at
  239. all — over the cap, and dumping it into the response would blow up the model's
  240. context anyway.
  241. - **How it works:** call `imap_get_attachment` with the `message_id` plus a
  242. selector — either `part_id` (the value `imap_get_message` reports for each
  243. attachment) or `filename`. The server fetches the full message (no size cap on
  244. the server side), extracts and decodes just that one part, and **writes it to
  245. disk**, returning `{ file_path, filename, content_type, part_id, size_bytes }`.
  246. The binary never enters the response, so context stays small. The saved path
  247. feeds straight into a local reader (e.g. an image-description tool or a PDF
  248. reader).
  249. - **Where files land:** `output_dir` argument if given, else the
  250. `MAIL_ATTACHMENT_DOWNLOAD_DIR` environment variable, else the system temp dir.
  251. Filenames are sanitized (basename only, control characters stripped) to
  252. prevent path traversal, and prefixed with the message UID and part id to avoid
  253. collisions.
  254. - **Optional inline base64:** set `include_base64: true` to also get the bytes
  255. in the response, but only when the attachment is at most `max_inline_bytes`
  256. (default 256 KiB). Off by default.
  257. ## What's New in v0.4.8
  258. - **`SAVE_SENT` is now per-account with a provider-aware default.**
  259. Previously, saving a copy of outgoing mail to the Sent folder via IMAP
  260. APPEND was controlled by a single global flag, `MAIL_SMTP_SAVE_SENT`. The
  261. problem: providers that **already save** sent mail server-side (Gmail,
  262. Zoho) ended up with **two identical copies** in Sent, while a generic SMTP
  263. server or Office 365 (which do **not** auto-save on SMTP submission) lost
  264. the copy entirely when the flag was `false`.
  265. - **Provider-aware default** (when nothing is configured):
  266. - **Gmail** (`smtp.gmail.com`): saves server-side and deduplicates by
  267. Message-ID → the MCP does **not** append (`false`).
  268. - **Zoho** (`smtp.zoho.com`): saves server-side but does **not**
  269. deduplicate → the MCP does **not** append (`false`), avoiding the
  270. duplicate.
  271. - **Office 365 / generic SMTP**: do **not** auto-save on SMTP submission →
  272. the MCP **does** append (`true`), or the sent copy would be lost.
  273. - **Per-account override**: `MAIL_SMTP_<ID>_SAVE_SENT=true|false` takes
  274. priority over everything. The global `MAIL_SMTP_SAVE_SENT` still works as a
  275. coarse override (wins over the provider default, loses to the per-account
  276. override).
  277. - Precedence: **per-account** → **global** → **provider-aware default**.
  278. | Provider | Auto-saves server-side | MCP default |
  279. |---|---|---|
  280. | Gmail | Yes (with dedupe) | `false` |
  281. | Zoho | Yes (no dedupe) | `false` |
  282. | Office 365 (SMTP) | No | `true` |
  283. | Generic SMTP / relays | No | `true` |
  284. ## What's New in v0.4.7
  285. - **Critical fix — `graph_send_message` silently dropped attachments on
  286. threaded replies.** When called with `in_reply_to` + `attachments`, the
  287. `createReply → PATCH → send` flow included the attachments in the PATCH
  288. against `/me/messages/{id}`. Microsoft Graph treats `Message.attachments`
  289. as a navigation property and **silently discards the field** on PATCH
  290. (2xx response, no error), so the message went out as single-part
  291. `text/html` with no file. The MCP returned `status: ok` and the caller
  292. assumed success. Invisible data loss.
  293. - **The fix:** in `send_via_reply()`, attachments are now uploaded one by one
  294. to `POST /me/messages/{draft_id}/attachments` between the PATCH and the
  295. send. Files < 3 MB go inline (JSON with base64 `contentBytes`); files
  296. ≥ 3 MB use `createUploadSession` with 4 MB chunked PUTs. The `attachments`
  297. field was removed from the `PatchDraftRequest` struct so the regression
  298. cannot be reintroduced by a type-correct edit.
  299. - **No change to flows that already worked.** `send_via_sendmail` (new
  300. messages without `in_reply_to`) uses `POST /me/sendMail` with `attachments`
  301. inline in the JSON — Graph DOES accept the field on that endpoint and never
  302. dropped it. That path is untouched.
  303. - **Regression test added:** `patch_draft_request_never_serializes_attachments`
  304. fails if anyone re-adds the field to the struct.
  305. - **Reference:** `BUG_GRAPH_ATTACHMENTS.md` at the repo root documents the
  306. full reproduction, root cause, and the empirical evidence behind the fix.
  307. ## What's New in v0.4.6
  308. - **Server-side enforcement of HARD RULE #1.** Three releases of prompt-only
  309. hardening (v0.4.3 → v0.4.4 → v0.4.5) still left LLMs occasionally leaking
  310. literal `</body_text><parameter name="body_html">` markup into the
  311. recipient's inbox. v0.4.6 adds a real validator that **rejects** the tool
  312. call before any SMTP / Graph / EWS attempt if `body_text` or `body_html`
  313. contains tool-call wrapper syntax. The check is wired into all 5 send
  314. paths (`smtp_send_message`, `smtp_reply_message`, `smtp_forward_message`,
  315. `graph_send_message`, `ews_send_message`).
  316. - The forbidden markers are case-insensitive and tightly scoped — only
  317. the pseudo-tags that have no legitimate use in human correspondence:
  318. `<body_text>`, `</body_text>`, `<body_html>`, `</body_html>`,
  319. `<function_calls>`, `</function_calls>`, `<invoke name=`, `</invoke>`,
  320. and `<parameter name="body_*">`. Generic technical content that happens
  321. to mention `<parameter>` for an XML schema or `<invoke>` in a code
  322. example still passes.
  323. - **HARD RULE #1 wording updated** to announce the server-side rejection,
  324. so the LLM knows it's a hard contract — not a suggestion it can ignore.
  325. - No breaking changes for clean callers: well-behaved messages send
  326. exactly as before.
  327. ## What's New in v0.4.5
  328. - **`serverInfo` now reports `name="mail-mcp"` + the crate `version`** (the
  329. framework previously returned its own `rmcp 0.16.0`, which never changes
  330. between releases). Useful for verifying the active version with `/mcp`, and
  331. so any client-side cache keyed by (server, version) invalidates on each bump.
  332. - **MCP instructions reorganized**: the 3 critical anti-concatenation rules
  333. (which in v0.4.3 and v0.4.4 sat at the end of the block and could be lost
  334. to truncation / diluted attention) now appear as **HARD RULE #1, #2, #3 at
  335. the TOP**, right after the title. Consolidated into 3 short paragraphs
  336. (previously 3 long sections, ~1500 characters combined).
  337. - **No functional changes to the server.** Same SMTP/IMAP/EWS/Graph, same
  338. tool set, same behavior. Only the text exposed to the client changed.
  339. ### Important for these rules to take effect
  340. Clients that resume a session with `claude --continue` (or `/resume`) do
  341. **NOT** refresh the MCP `system_prompt` — they keep the one from that
  342. session's first handshake. If your session predates v0.4.5, the rules won't
  343. reach your context even if the on-disk binary is updated. To receive them,
  344. start a NEW session in the project (not `--continue`).
  345. ## What's New in v0.4.4
  346. - **Preview hygiene rule** in MCP `instructions`: when the LLM shows the
  347. user the email preview before sending, it should render ONE clean
  348. version of the body (markdown-style bullets, bold, links as text + URL)
  349. and state that the message will go multipart — but it must NOT dump
  350. the raw HTML source (`<p>`, `<strong>`, `<a href>`...) into the
  351. preview. Two reasons:
  352. 1. The human reviewer wants to read the message, not audit markup —
  353. showing the HTML is noise.
  354. 2. Exhibiting both the plain-text string AND the HTML string side by
  355. side in the preview is exactly the context that has historically
  356. led LLMs to concatenate them in the eventual tool call (the bug
  357. v0.4.3 documented). Hiding the HTML source from the preview
  358. removes the temptation.
  359. Complements the **PREVIEW DOES NOT EQUAL TOOL CALL** rule introduced
  360. in v0.4.3.
  361. ## What's New in v0.4.3
  362. - **Server-side guidance against malformed tool calls.** The MCP
  363. `instructions` block now explicitly tells the calling LLM that
  364. `body_text` and `body_html` are TWO SEPARATE JSON fields and must
  365. NEVER be concatenated. Previous wording ("send BOTH body_text AND
  366. body_html") was ambiguous and some LLMs interpreted it as "concatenate
  367. both with `<body_text>...</body_html>` pseudo-tags inside a single
  368. `body_text` string". When that happens, the recipient sees garbled
  369. duplicated content, AND any later Claude session that opens the saved
  370. copy via this MCP gets a Usage Policy block (the leaked
  371. `<invoke>...</invoke>` looks like a prompt-injection attempt to safety
  372. filters). The new instruction shows a CORRECT vs WRONG example and
  373. bans pseudo-tags / tool-call wrapper syntax inside email fields.
  374. ## What's New in v0.4.2
  375. - **Release pipeline fixed**: the `publish-npm` job in the CI release
  376. workflow has been disabled. It was inherited from the upstream fork and
  377. tried to publish to `@bradsjm/mail-imap-mcp-rs`, a scope this org does
  378. not own — every release was 404-ing on that step. See "Releasing" below
  379. for the full explanation and how to re-enable npm publishing if needed.
  380. - **Auto-trigger releases on tag push**: `.github/workflows/release.yml`
  381. now fires on `push: tags: ['v*']`, so tagging `vX.Y.Z` and pushing is
  382. all it takes to cut a release. `workflow_dispatch` is retained as a
  383. manual escape hatch.
  384. - **Cleanup**: removed the dangling `init-npm-placeholder.yml` workflow
  385. (also referenced the fork's npm scope).
  386. - **docs**: README gains a "Releasing" section documenting the new flow
  387. and the npm decision.
  388. ## What's New in v0.4.1
  389. - **Fix**: `save_to_sent_folder` now archives the exact RFC822 bytes that were
  390. sent (via `lettre.formatted()`), instead of a hand-rolled text-only stub.
  391. The Sent-folder copy keeps the HTML body, the multipart/alternative
  392. structure, and the RFC 2047-encoded subject — no more `???` where accents
  393. used to be, and HTML is no longer silently dropped.
  394. - **Improved**: localized Sent-folder detection — `Enviado[s]`, `Elementos
  395. enviados`, `Enviadas`, `Itens enviados`, `Envoyés`, `Éléments envoyés`,
  396. `Gesendet`, `Posta inviata`, `Verzonden`, `Wysłane`, plus nested variants.
  397. Previously only English names were recognized, so Zoho/localized IMAP
  398. accounts fell through to a non-existent `"Sent"` folder.
  399. - **Improved**: `smtp_forward_message` accepts `body_html` (was hardcoded to
  400. plain-text only).
  401. - **Improved**: EWS send gains `bcc`, `in_reply_to`, `references` (via
  402. `<t:InternetMessageHeaders>`), plus full recipient + subject-length
  403. validation — now at parity with the SMTP and Graph send paths.
  404. - **Improved**: Graph API threading fallbacks now log. `WARN` when the
  405. message-lookup HTTP call fails (rate limit, 5xx, permissions) so operators
  406. see threading degraded due to a real error; `DEBUG` when the original
  407. message is legitimately not found.
  408. - **Refactor**: EWS XML parsing migrated from substring matching to
  409. `quick-xml`. Fixes a latent namespace-collision bug (`<soap:Body>` vs
  410. `<t:Body>`), correctly decodes XML entities and CDATA, and handles
  411. attribute values containing `=` (common in base64-like EWS item IDs).
  412. - **Cleanup**: zero warnings on `cargo build --release`.
  413. - **Tests**: 64 (up from 47).
  414. ## Why This Project
  415. | | mail-mcp | Typical email MCP |
  416. |---|:---:|:---:|
  417. | IMAP read/write | 18 tools | 3-5 tools |
  418. | SMTP send/reply/forward | Yes | No or broken |
  419. | Microsoft Graph API | Yes | No |
  420. | EWS (Exchange Web Services) | Yes | No |
  421. | OAuth2 (XOAUTH2) | Native | No |
  422. | Multi-account | Yes | Single account |
  423. | Microsoft 365 + Hotmail | Both work | Usually neither |
  424. | Language | Rust (fast, safe) | TypeScript/Python |
  425. | Tests | 64 unit + integration | Mocks only |
  426. | Warnings in release build | 0 | Varies |
  427. ## Feature Matrix
  428. | Provider | IMAP | SMTP | Graph API | EWS | OAuth2 | Multi-account |
  429. |----------|:----:|:----:|:---------:|:---:|:------:|:-------------:|
  430. | Microsoft 365 (enterprise) | Yes | Admin-dependent | Yes | **Yes** | Yes | Yes |
  431. | Hotmail / Outlook.com | Yes | Blocked by MS | Yes | **Yes** | Yes | Yes |
  432. | Gmail | Yes | Yes | — | — | Yes | Yes |
  433. | Apple iCloud | Yes | Yes | — | — | — | Yes |
  434. | Zoho | Yes | Yes | — | — | — | Yes |
  435. | Fastmail | Yes | Yes | — | — | — | Yes |
  436. | Any IMAP/SMTP server | Yes | Yes | — | — | — | Yes |
  437. > **EWS is the simplest way to add Microsoft accounts** — single OAuth2 token for both reading and sending. Works even on tenants that block Graph API and IMAP.
  438. ## Quickstart — Let Claude Code do it
  439. Copy and paste this prompt into Claude Code and it will install, compile, and configure everything for you:
  440. ```
  441. Install and configure the mail-mcp MCP server from https://github.com/tecnologicachile/mail-mcp
  442. 1. Clone the repo, build with cargo build --release
  443. 2. Add the MCP server to .claude.json with the binary path
  444. 3. For Microsoft accounts: use EWS (simplest) — run device code flow with
  445. client_id d3590ed6-52b3-4102-aeff-aad2292ab01c and scope
  446. https://outlook.office.com/EWS.AccessAsUser.All offline_access
  447. Then configure MAIL_EWS_<ID>_USER and MAIL_EWS_<ID>_REFRESH_TOKEN
  448. 4. For Gmail: configure MAIL_IMAP + MAIL_SMTP with App Password from
  449. https://myaccount.google.com/apppasswords
  450. 5. For Zoho: configure MAIL_IMAP + MAIL_SMTP with standard password
  451. 6. Enable write/send: MAIL_IMAP_WRITE_ENABLED=true, MAIL_SMTP_WRITE_ENABLED=true
  452. My email accounts to configure:
  453. - <your-email@example.com>
  454. ```
  455. Replace the last line with your email(s). Claude Code will guide you through each step including the OAuth2 device code flow for Microsoft accounts.
  456. ## Manual Setup
  457. Install a prebuilt binary:
  458. ```bash
  459. # macOS and Linux (Homebrew)
  460. brew install tecnologicachile/tap/mail-mcp
  461. # macOS and Linux (shell installer)
  462. curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tecnologicachile/mail-mcp/releases/latest/download/mail-mcp-installer.sh | sh
  463. ```
  464. The shell and PowerShell installers also install `mail-mcp-update`, which
  465. updates an existing install to the latest release. With Homebrew, use
  466. `brew upgrade mail-mcp`.
  467. ```powershell
  468. # Windows
  469. powershell -ExecutionPolicy Bypass -c "irm https://github.com/tecnologicachile/mail-mcp/releases/latest/download/mail-mcp-installer.ps1 | iex"
  470. ```
  471. Or build from source:
  472. ```bash
  473. git clone https://github.com/tecnologicachile/mail-mcp.git
  474. cd mail-mcp
  475. cargo build --release
  476. ```
  477. Create the default TOML file and add an account in a terminal. For a source
  478. build, replace `mail-mcp` with `./target/release/mail-mcp`:
  479. ```bash
  480. mail-mcp config init
  481. mail-mcp accounts add
  482. mail-mcp accounts list
  483. mail-mcp config validate
  484. mail-mcp accounts test default
  485. ```
  486. Choose `default` as the account ID above, or substitute the chosen ID in the
  487. test command. Passwords and tokens use hidden prompts. OAuth accounts require
  488. credentials obtained beforehand; the CLI does not perform initial login or
  489. token acquisition. `config init` refuses to overwrite a file, and connection
  490. tests do not send or change mail.
  491. Add this entry to the MCP client configuration (Claude Code, Cursor, etc.):
  492. ```json
  493. {
  494. "mcpServers": {
  495. "mail": {
  496. "command": "mail-mcp"
  497. }
  498. }
  499. }
  500. ```
  501. Use an absolute binary path if necessary. The server loads
  502. `~/.mail-mcp/config.toml`; no credentials are needed in the client JSON.
  503. Writes, sends, and drafts remain disabled until enabled in the configuration.
  504. `--config PATH` takes precedence over `MAIL_CONFIG_FILE`, then the default path.
  505. Process `MAIL_*` settings override file fields. Implicit `.env` loading applies
  506. only when no TOML path is explicitly selected and no default TOML file exists.
  507. See [guided setup and account management](docs/account-setup.md#guided-setup-with-toml)
  508. and the [TOML reference](docs/advanced-configuration.md#toml-configuration) for
  509. edit/remove commands, all fields, and an MCP-client `MAIL_CONFIG_FILE` example.
  510. ### Environment-Only Configuration
  511. Environment-only setup remains supported. Instead of creating a TOML file,
  512. place account settings in the MCP client's `env` object. With a prebuilt
  513. binary, use `"command": "mail-mcp"`:
  514. ```json
  515. {
  516. "mcpServers": {
  517. "mail": {
  518. "command": "./target/release/mail-mcp",
  519. "env": {
  520. "MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
  521. "MAIL_IMAP_DEFAULT_USER": "you@gmail.com",
  522. "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
  523. "MAIL_SMTP_DEFAULT_HOST": "smtp.gmail.com",
  524. "MAIL_SMTP_DEFAULT_PORT": "587",
  525. "MAIL_SMTP_DEFAULT_USER": "you@gmail.com",
  526. "MAIL_SMTP_DEFAULT_PASS": "your-app-password",
  527. "MAIL_SMTP_DEFAULT_SECURE": "starttls",
  528. "MAIL_IMAP_WRITE_ENABLED": "true",
  529. "MAIL_SMTP_WRITE_ENABLED": "true"
  530. }
  531. }
  532. }
  533. }
  534. ```
  535. This environment example explicitly enables read, write, and send operations.
  536. A default `~/.mail-mcp/config.toml` applies to every client that does not
  537. select a file, including this one. Add `"MAIL_CONFIG_FILE": "none"` to the
  538. `env` object to keep the client environment-only.
  539. ### Microsoft Account? Use Graph API
  540. Microsoft blocks SMTP on personal accounts. Use Graph API instead:
  541. ```json
  542. {
  543. "env": {
  544. "MAIL_IMAP_DEFAULT_HOST": "outlook.office365.com",
  545. "MAIL_IMAP_DEFAULT_USER": "you@hotmail.com",
  546. "MAIL_IMAP_DEFAULT_PASS": "your-app-password",
  547. "MAIL_OAUTH2_DEFAULT_PROVIDER": "microsoft",
  548. "MAIL_OAUTH2_DEFAULT_CLIENT_ID": "9e5f94bc-e8a4-4e73-b8be-63364c29d753",
  549. "MAIL_OAUTH2_DEFAULT_CLIENT_SECRET": "none",
  550. "MAIL_OAUTH2_DEFAULT_REFRESH_TOKEN": "<your-token>"
  551. }
  552. }
  553. ```
  554. Get your token in 1 minute with device code flow. See [Account Setup Guide](docs/account-setup.md).
  555. ## 37 MCP Tools
  556. ### Read (10 tools)
  557. | Tool | What it does |
  558. |------|-------------|
  559. | `list_all_accounts` | **List all accounts with capabilities** (IMAP, SMTP, Graph, EWS) |
  560. | `imap_list_accounts` | List IMAP accounts |
  561. | `imap_verify_account` | Test connectivity and auth |
  562. | `imap_list_mailboxes` | List folders |
  563. | `imap_mailbox_status` | Message counts |
  564. | `imap_search_messages` | Search with cursor pagination; `thread_message_id` finds a message and its replies |
  565. | `imap_search_all_mailboxes` | Same criteria in every mailbox at once (e.g. a whole conversation spread over INBOX, Sent and project folders), newest first, labelled with the mailbox |
  566. | `imap_get_message` | Parsed message (text, HTML, attachments) |
  567. | `imap_get_message_raw` | RFC822 source |
  568. | `imap_get_attachment` | Download one attachment to disk (bypasses the raw size cap) |
  569. ### Write (11 tools)
  570. | Tool | What it does |
  571. |------|-------------|
  572. | `imap_update_message_flags` | Add/remove flags |
  573. | `imap_copy_message` | Copy (cross-account supported) |
  574. | `imap_move_message` | Move to folder |
  575. | `imap_delete_message` | Delete with confirmation |
  576. | `imap_create_mailbox` | Create folder |
  577. | `imap_delete_mailbox` | Delete folder |
  578. | `imap_rename_mailbox` | Rename folder |
  579. | `imap_append_message` | Append raw message |
  580. | `imap_bulk_move` | Move up to 500 at once |
  581. | `imap_bulk_delete` | Delete up to 500 at once |
  582. | `imap_bulk_update_flags` | Flag up to 500 at once |
  583. ### Send (5 tools)
  584. | Tool | What it does |
  585. |------|-------------|
  586. | `smtp_send_message` | Send email (text/HTML, CC/BCC) |
  587. | `smtp_reply_message` | Reply with threading headers |
  588. | `smtp_forward_message` | Forward with original inline |
  589. | `smtp_verify_account` | Test SMTP connectivity |
  590. | `graph_send_message` | Send via Microsoft Graph API (with reply threading) |
  591. ### EWS — Exchange Web Services (3 tools)
  592. | Tool | What it does |
  593. |------|-------------|
  594. | `ews_search_messages` | Search emails via EWS (inbox, sent, drafts, etc.) |
  595. | `ews_get_message` | Get full email content via EWS |
  596. | `ews_send_message` | Send email via EWS |
  597. ### Drafts (5 tools)
  598. The agent prepares the email, a person reviews it in their mail client (or
  599. asks the agent to send it). One set of tools for every account: drafts go to
  600. the IMAP Drafts folder, or through EWS or Microsoft Graph when the account is
  601. configured for them (`list_all_accounts` shows `drafts_with`).
  602. | Tool | What it does |
  603. |------|-------------|
  604. | `draft_create` | Save a new draft (CC/BCC, HTML, attachments, threading) |
  605. | `draft_update` | Replace a draft's content; returns a new `draft_id` |
  606. | `draft_send` | Send a draft and remove it from Drafts |
  607. | `draft_delete` | Delete a draft (only drafts; needs `confirm: true`) |
  608. | `draft_list` | List drafts, newest first |
  609. Enable with `MAIL_DRAFTS_ENABLED=true`. It is independent of
  610. `MAIL_IMAP_WRITE_ENABLED`: with only drafts enabled, the agent can write
  611. drafts but cannot move, flag or delete other mail, and every draft tool
  612. refuses ids that are not drafts. `draft_send` additionally needs
  613. `MAIL_SMTP_WRITE_ENABLED=true`. Graph accounts need the `Mail.ReadWrite`
  614. scope.
  615. ### Attachments
  616. Send files with any send tool. Two modes:
  617. ```json
  618. // Large files — MCP reads from disk (recommended)
  619. "attachments": [{"file_path": "/path/to/report.pdf"}]
  620. // Small files — inline base64
  621. "attachments": [{"filename": "note.txt", "content_type": "text/plain", "content_base64": "SGVsbG8="}]
  622. ```
  623. Filename and MIME type are auto-detected from the file path. Reply with `include_original_attachments: true` to forward original attachments.
  624. **Downloading** an attachment from a received message: use `imap_get_attachment`
  625. with the `message_id` and a `part_id` (from `imap_get_message`) or `filename`.
  626. It writes the decoded file to disk and returns the path — no size cap, and the
  627. binary stays out of the response. Set the default download directory with
  628. `MAIL_ATTACHMENT_DOWNLOAD_DIR` (falls back to the system temp dir), or pass
  629. `output_dir` per call.
  630. To limit which local files send tools may attach via `file_path`, set
  631. `MAIL_ATTACHMENT_UPLOAD_DIR`; paths outside it (including via `..` or
  632. symlinks) are rejected. See [docs/security.md](docs/security.md#outbound-attachment-scope).
  633. ### Bulk Operations (2 tools)
  634. | Tool | What it does |
  635. |------|-------------|
  636. | `imap_search_and_move` | Search + move matches |
  637. | `imap_search_and_delete` | Search + delete matches |
  638. ### Setup Helper (1 tool)
  639. | Tool | What it does |
  640. |------|-------------|
  641. | `get_setup_guide` | Provider-specific setup instructions (Microsoft OAuth2, Gmail/iCloud App Passwords, Zoho, etc.) |
  642. ## Multi-Account
  643. Configure as many accounts as you need:
  644. ```bash
  645. # Gmail
  646. MAIL_IMAP_GMAIL_HOST=imap.gmail.com
  647. MAIL_IMAP_GMAIL_USER=me@gmail.com
  648. MAIL_IMAP_GMAIL_PASS=app-password
  649. # Apple iCloud (App-Specific Password from appleid.apple.com)
  650. MAIL_IMAP_ICLOUD_HOST=imap.mail.me.com
  651. MAIL_IMAP_ICLOUD_USER=you@icloud.com
  652. MAIL_IMAP_ICLOUD_PASS=app-specific-password
  653. MAIL_SMTP_ICLOUD_HOST=smtp.mail.me.com
  654. MAIL_SMTP_ICLOUD_USER=you@icloud.com
  655. MAIL_SMTP_ICLOUD_PASS=app-specific-password
  656. MAIL_SMTP_ICLOUD_SECURE=starttls
  657. # Microsoft 365
  658. MAIL_IMAP_WORK_HOST=outlook.office365.com
  659. MAIL_IMAP_WORK_USER=me@company.com
  660. MAIL_OAUTH2_WORK_PROVIDER=microsoft
  661. MAIL_OAUTH2_WORK_CLIENT_ID=your-client-id
  662. MAIL_OAUTH2_WORK_CLIENT_SECRET=none
  663. MAIL_OAUTH2_WORK_REFRESH_TOKEN=your-token
  664. # Zoho
  665. MAIL_IMAP_DEFAULT_HOST=imap.zoho.com
  666. MAIL_IMAP_DEFAULT_USER=info@mydomain.com
  667. MAIL_IMAP_DEFAULT_PASS=password
  668. MAIL_SMTP_DEFAULT_HOST=smtp.zoho.com
  669. MAIL_SMTP_DEFAULT_USER=info@mydomain.com
  670. MAIL_SMTP_DEFAULT_PASS=password
  671. MAIL_SMTP_DEFAULT_SECURE=starttls
  672. ```
  673. Use `account_id` in tool calls: `"account_id": "gmail"`, `"account_id": "icloud"`, `"account_id": "work"`, `"account_id": "default"`.
  674. ## Security
  675. - **TLS enforced** on all connections (except localhost proxies)
  676. - **Passwords in SecretString** — never logged or returned in responses
  677. - **Write operations gated** — require explicit `MAIL_IMAP_WRITE_ENABLED=true`
  678. - **Send operations gated** — require explicit `MAIL_SMTP_WRITE_ENABLED=true`
  679. - **Drafts gated separately** — `MAIL_DRAFTS_ENABLED=true` allows writing drafts without any other write access
  680. - **Delete confirmation** — requires `confirm: true`
  681. - **HTML sanitized** with ammonia (prevents XSS)
  682. - **Bounded outputs** — body text, HTML, attachments truncated to configurable limits
  683. - **OAuth2 tokens cached** with 10-minute refresh margin
  684. - **No secrets in responses** — credentials never exposed via MCP tools
  685. - **HTTP transport is opt-in and unauthenticated** — stdio by default; `MAIL_MCP_TRANSPORT=http` binds to loopback unless told otherwise, and belongs behind an authenticating gateway
  686. ## Configuration Reference
  687. For TOML fields, account examples, path selection, and environment overrides,
  688. see the [TOML configuration reference](docs/advanced-configuration.md#toml-configuration).
  689. <details>
  690. <summary>Full environment variable reference</summary>
  691. ### IMAP (per account)
  692. | Variable | Required | Default | Description |
  693. |----------|----------|---------|-------------|
  694. | `MAIL_IMAP_<ID>_HOST` | Yes | — | IMAP server |
  695. | `MAIL_IMAP_<ID>_PORT` | No | 993 | IMAP port |
  696. | `MAIL_IMAP_<ID>_USER` | Yes | — | Username |
  697. | `MAIL_IMAP_<ID>_PASS` | Yes* | — | Password (*optional with OAuth2) |
  698. | `MAIL_IMAP_<ID>_SECURE` | No | true | Use TLS |
  699. ### SMTP (per account)
  700. | Variable | Required | Default | Description |
  701. |----------|----------|---------|-------------|
  702. | `MAIL_SMTP_<ID>_HOST` | Yes | — | SMTP server |
  703. | `MAIL_SMTP_<ID>_PORT` | No | 587 | SMTP port |
  704. | `MAIL_SMTP_<ID>_USER` | Yes | — | Username |
  705. | `MAIL_SMTP_<ID>_PASS` | No | — | Password (optional with OAuth2) |
  706. | `MAIL_SMTP_<ID>_SECURE` | No | starttls | `starttls`, `tls`, or `plain` |
  707. | `MAIL_SMTP_<ID>_FROM_EMAIL` | No | = `_USER` | Sender address when it differs from the SMTP auth username (e.g. shared/group mailboxes) |
  708. ### OAuth2 (per account)
  709. | Variable | Required | Default | Description |
  710. |----------|----------|---------|-------------|
  711. | `MAIL_OAUTH2_<ID>_PROVIDER` | Yes | — | `google` or `microsoft` |
  712. | `MAIL_OAUTH2_<ID>_CLIENT_ID` | Yes | — | OAuth2 client ID |
  713. | `MAIL_OAUTH2_<ID>_CLIENT_SECRET` | Yes | — | Client secret (`none` for public clients) |
  714. | `MAIL_OAUTH2_<ID>_REFRESH_TOKEN` | Yes | — | Refresh token |
  715. ### Graph API OAuth2 (per account)
  716. | Variable | Required | Default | Description |
  717. |----------|----------|---------|-------------|
  718. | `MAIL_GRAPH_<ID>_PROVIDER` | Yes | — | `microsoft` |
  719. | `MAIL_GRAPH_<ID>_CLIENT_ID` | Yes | — | OAuth2 client ID |
  720. | `MAIL_GRAPH_<ID>_CLIENT_SECRET` | Yes | — | Client secret (`none` for public clients) |
  721. | `MAIL_GRAPH_<ID>_REFRESH_TOKEN` | Yes | — | Refresh token (Mail.Send scope) |
  722. ### EWS — Exchange Web Services (per account, simplest for Microsoft)
  723. | Variable | Required | Default | Description |
  724. |----------|----------|---------|-------------|
  725. | `MAIL_EWS_<ID>_USER` | Yes | — | Email address |
  726. | `MAIL_EWS_<ID>_REFRESH_TOKEN` | Yes | — | OAuth2 refresh token (EWS scope) |
  727. | `MAIL_EWS_<ID>_CLIENT_ID` | No | `d3590ed6...` (Microsoft Office) | OAuth2 client ID |
  728. | `MAIL_EWS_<ID>_CLIENT_SECRET` | No | `none` | Client secret |
  729. > **Tip:** EWS only needs 2 variables (USER + REFRESH_TOKEN). Client ID defaults to Microsoft Office which has all permissions pre-approved.
  730. ### Global Settings
  731. | Variable | Default | Description |
  732. |----------|---------|-------------|
  733. | `MAIL_IMAP_WRITE_ENABLED` | false | Enable IMAP write operations |
  734. | `MAIL_SMTP_WRITE_ENABLED` | false | Enable SMTP/Graph send operations |
  735. | `MAIL_DRAFTS_ENABLED` | false | Enable the draft tools (`draft_send` also needs `MAIL_SMTP_WRITE_ENABLED`) |
  736. | `MAIL_SMTP_SAVE_SENT` | unset | Global Sent-copy override; per-account choice wins, otherwise Gmail/Zoho skip the IMAP copy and other hosts save it |
  737. | `MAIL_SMTP_CONNECT_TIMEOUT_MS` | 30000 | SMTP TCP/TLS/auth timeout (connect phase) |
  738. | `MAIL_SMTP_SEND_TIMEOUT_MS` | 300000 | SMTP DATA transmission timeout (5 min — accommodates large attachments) |
  739. | `MAIL_SMTP_TIMEOUT_MS` | _(deprecated)_ | Legacy send timeout; process value overrides TOML unless `MAIL_SMTP_SEND_TIMEOUT_MS` is also set in the environment. Prefer the split vars above. |
  740. | `MAIL_IMAP_CONNECT_TIMEOUT_MS` | 30000 | TCP connection timeout |
  741. | `MAIL_IMAP_GREETING_TIMEOUT_MS` | 15000 | TLS/greeting timeout |
  742. | `MAIL_IMAP_SOCKET_TIMEOUT_MS` | 300000 | Socket I/O timeout |
  743. | `MAIL_IMAP_MAX_MAILBOXES` | 200 | Max mailboxes `imap_list_mailboxes` returns (1–10000); the response reports `total` and `truncated` |
  744. | `MAIL_IMAP_SEARCH_CONCURRENCY` | 4 | Parallel IMAP connections for `imap_search_all_mailboxes` (1–8) |
  745. | `MAIL_OAUTH2_TOKEN_STORE` | _(unset)_ | File where rotated OAuth2 refresh tokens are saved so they survive a restart (see [OAuth2 token store](docs/advanced-configuration.md#oauth2-token-store)) |
  746. | `MAIL_MCP_TRANSPORT` | stdio | `stdio`, or `http` to serve MCP streamable HTTP (see [Remote HTTP transport](docs/advanced-configuration.md#remote-http-transport)) |
  747. | `MAIL_MCP_HTTP_HOST` | 127.0.0.1 | HTTP bind address (IP literal) |
  748. | `MAIL_MCP_HTTP_PORT` | 8000 | HTTP bind port |
  749. | `MAIL_MCP_HTTP_PATH` | /mcp | HTTP endpoint path |
  750. </details>
  751. ## Roadmap
  752. - [x] IMAP read operations (search, fetch, parse)
  753. - [x] IMAP write operations (copy, move, delete, flags)
  754. - [x] IMAP bulk operations (up to 500 per call)
  755. - [x] Cursor-based pagination with TTL
  756. - [x] SMTP send, reply, forward
  757. - [x] Microsoft Graph API (sendMail)
  758. - [x] OAuth2 XOAUTH2 (Google + Microsoft)
  759. - [x] Separate Graph API tokens for enterprise
  760. - [x] Multi-account via environment variables
  761. - [x] PDF text extraction from attachments
  762. - [x] HTML sanitization (ammonia)
  763. - [x] Provider setup documentation with direct links
  764. - [x] Attachment sending (SMTP/Graph)
  765. - [x] Reply with original attachments
  766. - [x] CDATA sanitization (Zoho bug fix)
  767. - [x] Email confirmation protocol (preview before send)
  768. - [x] Token-optimized instructions (75% reduction)
  769. - [x] On-demand setup guide tool
  770. - [x] **EWS (Exchange Web Services)** — single token for read + send on Microsoft
  771. - [x] EWS with Microsoft Office Client ID (works on restricted tenants)
  772. - [x] **Graph API threading** — `createReply` flow for proper conversation threading
  773. - [x] **HTML formatting guidance** — LLM prefers multipart (text + HTML) for human emails
  774. - [x] **Sent folder archiving preserves full MIME** — byte-identical copy of what the recipient received (v0.4.1)
  775. - [x] **Localized Sent folder detection** — Spanish / Portuguese / French / German / Italian / Dutch / Polish (v0.4.1)
  776. - [x] **EWS feature parity with SMTP/Graph** — BCC, threading headers, recipient validation (v0.4.1)
  777. - [x] **EWS XML parser via `quick-xml`** — correct entity/CDATA/namespace handling (v0.4.1)
  778. ### Next — Local cache with instant search
  779. - [ ] **SQLite + FTS5 local email cache** — instant searches (<10ms vs 3-10s)
  780. - [ ] **Incremental sync** — UIDVALIDITY + last UID delta sync
  781. - [ ] **Connection pooling** — persistent IMAP sessions per account
  782. - [ ] **Cross-account search** — search all accounts at once
  783. - [ ] **Email statistics** — counts, top senders, activity by date
  784. ### Future
  785. - [ ] Docker image
  786. - [ ] npm/npx distribution
  787. - [ ] Draft management
  788. - [ ] Contact search
  789. - [ ] IMAP IDLE (real-time notifications)
  790. - [ ] Hosted documentation site
  791. ## Documentation
  792. | Guide | Description |
  793. |-------|-------------|
  794. | [Account Setup](docs/account-setup.md) | Guided CLI setup, account management, provider credentials, and environment-only setup |
  795. | [Tool Contract](docs/tool-contract.md) | Complete tool definitions and schemas |
  796. | [Message ID Format](docs/message-id-format.md) | Stable message identifier format |
  797. | [Cursor Pagination](docs/cursor-pagination.md) | Pagination behavior and expiration |
  798. | [Security](docs/security.md) | Security features and best practices |
  799. | [Advanced Configuration](docs/advanced-configuration.md) | TOML field reference, configuration precedence, timeouts, and performance tuning |
  800. ## Development
  801. ```bash
  802. cargo test # 64 unit + integration tests
  803. cargo fmt -- --check # formatting
  804. cargo clippy --all-targets -- -D warnings # linting
  805. ```
  806. See `AGENTS.md` for contributor guidelines.
  807. ## Releasing
  808. Releases are automated via [`cargo-dist`](https://github.com/axodotdev/cargo-dist). To ship a new version:
  809. 1. Bump `version = "X.Y.Z"` in `Cargo.toml` (the release workflow enforces
  810. that this matches the pushed tag).
  811. 2. Commit the bump + any release notes to `main`.
  812. 3. Tag and push:
  813. ```bash
  814. git tag vX.Y.Z
  815. git push origin main --tags
  816. ```
  817. 4. The `push: tags: ['v*']` trigger in `.github/workflows/release.yml`
  818. compiles binaries for Linux / macOS (Intel + Apple Silicon) / Windows,
  819. generates installer scripts (`.sh`, `.ps1`), creates the GitHub Release,
  820. and attaches all artifacts with SHA256 checksums.
  821. 5. If anything fails you can re-run the workflow manually from the Actions
  822. tab (the `workflow_dispatch` trigger is preserved as an escape hatch).
  823. **npm publishing is intentionally disabled.** The upstream fork was
  824. configured to publish as `@bradsjm/mail-imap-mcp-rs`, a scope this
  825. organization does not own, which caused every release to 404 on `npm
  826. publish`. The npm tarball is still generated and attached to each GitHub
  827. Release so users can install via `npm install ./mail-mcp-npm-package.tar.gz`
  828. manually. To enable npm registry publishing for this fork: create an npm
  829. org (e.g. `@tecnologicachile`), configure Trusted Publishing on
  830. npmjs.com pointing at this repo, set `publish-jobs = ["npm"]` in
  831. `dist-workspace.toml`, and run `dist generate --allow-dirty` to restore
  832. the `publish-npm` job in `release.yml`.
  833. ## Contributing
  834. Contributions welcome! Check out the [issues](https://github.com/tecnologicachile/mail-mcp/issues) for good first issues.
  835. If mail-mcp is useful to you, a ⭐ on the repo helps others discover it.
  836. ## License
  837. MIT License — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.