Repository navigation
Releases
v0.3.6
A safety and reliability release. A full review of the app by several models found about 120 problems; this release fixes most of them. Some behavior is stricter than before; see Changed.
Changed (stricter than before)
- A one-message tool given a UID range or list (
1:*,1,2) is refused instead of acting on many messages. delete_mailboxrefuses a folder that still holds mail.send_draftonly sends messages from the Drafts folder, then moves them to Trash.- Local rules refuse catch-all patterns and moves into special-use folders (Trash, Junk, Drafts, Sent, Archive) or watched folders, and check labels. Old catch-all rules still load and run, with a warning.
- Sieve: a script that includes a server-wide script, or runs
filterwith a program not listed in the new[sieve] allowed_programs, is refused. You cannot delete a script the active script includes, or a backup that is the only copy of a script. - The alert webhook can only be set in
config.toml;configure_alertsno longer takeswebhook_urlorwebhook_events. - The scheduler sends nothing while
read_onlyis on; queued mail waits. download_attachmentandexport_emailrefuse file names that start with a dot and types that run when opened (.command,.terminal,.app,.scpt,.sh,.plist).- If the writer lock cannot be used, the watcher, hooks and alerts pause until it works, instead of running in every window.
- With the account set by environment variables,
[settings]still come fromconfig.toml(a line says so), andread_onlyon in either place wins. Yes/no variables are read strictly; a value likeenabledstops the start. Two accounts with the same name stop the start. - An IMAP account with both
tlsandstarttlsloads with a warning and uses implicit TLS.
Added
allow_duplicateonsend_email,reply_email,forward_emailandsend_draft;occurrenceondownload_attachment(and--occurrenceon the CLI) for two attachments with the same name.[sieve] allowed_programs(envMCP_EMAIL_SIEVE_ALLOWED_PROGRAMS) and a per-accountappend_sentsetting (off by default for Gmail, which files sent mail itself).- Forwards carry an
X-IMAP-Wizard-Forwardedheader, and rules never forward a marked message.
Fixed
- Sending: two identical sends at once now produce one send. A send that may or may not have reached the server is reported as "unknown, check Sent first" and never retried. A refused recipient no longer makes other queued sends fail. Replies say who received them and warn when Reply-To is on another domain.
- Scheduler: scheduled mail is never resent after the server may have taken it. A short outage no longer fails a job for good. Failed and unknown jobs are visible and can be cancelled. OAuth accounts work, and every scheduled send is in the audit log.
- Drafts, folders, expunge: editing a draft, deleting a folder or expunging no longer loses other mail. Permanent delete on a server without UIDPLUS works, with a warning.
- Watcher: an email with a bad date, a STARTTLS failure or a restart no longer stops the watcher. Mail that arrived during a gap of under an hour is caught up.
- Connections: the 30-minute connection rotation waits until nothing is using the connection. The 60-second mailbox wait also covers opening the mailbox. The first cache sync fetches in chunks of 500 and resumes if cut off. Move, delete, mark and bulk actions cut off by a dropped connection say the server may have done it.
- OAuth: one token refresh per account, bad answers refused, 30-second limit, rotated refresh tokens kept, and the mail sender rebuilt before its token runs out.
- Cache: an account name pointed at another server drops its old cached mail. A cache from a newer build is left alone, and a broken cache file is replaced.
account deleteremoves that account's cached mail. - Passwords: an account whose Keychain item or password command can't be read never logs in with the wrong text; other accounts keep working. Passwords and tokens are scrubbed from error text in more forms.
- CLI:
account addno longer overwrites a config file it cannot read, andaccount editkeeps settings it does not ask about.keychain removeandmigratedo nothing when you answer No.config.tomlis written safely, with the previous copy kept asconfig.toml.bak.scheduler uninstallleaves other cron lines alone.imap-wizard readprints no terminal control codes. - HTTP mode: repeated and simultaneous calls work, and SIGTERM exits cleanly.
- Attachments: two with the same name keep their own bytes; inline and name-only PDFs are listed and forwarded; saved files are never overwritten; one failed attachment no longer hides the others.
savePathallows files up to 50 MB. A message body that did not download is reported instead of shown as empty. - Calendar: attachments are saved only after you accept the dialog, the dialog shows the real date, and an unreadable email date no longer builds a calendar script. Calendar and Reminders lists report a refused permission instead of an empty list.
- Rules: edits at the same time no longer lose each other, matching can no longer freeze the app, and removing a forward address applies at once. Scheduled emails and rules stop when their account now points at a different server or login.
- Audit log: a full or broken audit log no longer makes a finished action look like it failed.
list_templatesnames broken template files, and a failed batch of new mail is logged.
Security
- Windows desktop alerts no longer run PowerShell code from an email subject.
- Tool results that contain email text are marked as untrusted, including structured results (
untrusted: true), calendar, contacts, stats and Sieve server text. AI triage can no longer have its fence closed by a subject line. get_email_securitytrusts only the top authentication header and your own server's headers.get_verification_codefences the link and warns when its host is not the sender's.get_emailwithmarkReadis refused on a read-only server.- The audit log, calendar state, attachments and cache files are owner-only (0600/0700). A
config.tomlreadable by others gets a warning. - Releases build only real version tags, outside actions are pinned to commits, and the downloaded
mcp-publisheris checked against its sha256.
Docs
- README covers the per-process send limit, the forward allowlist (read live from
config.toml, for standing forwards only), what read-only mode covers, and Docker volumes for the state and data folders.
Install: npx -y imap-wizard, or docker pull ghcr.io/fe2-o3/imap-wizard:v0.3.6
v0.3.5
Added
- Server-side filter rules (Sieve over ManageSieve):
sieve_status,sieve_list_scripts,sieve_get_script,sieve_check_script,sieve_put_script,sieve_activate_script,sieve_delete_script. Previews and diffs by default (apply: trueto save), the server's CHECKSCRIPT when offered, automatic backups before replace or delete, refusal to delete the active script,disableAll: trueneeded to turn every script off. STARTTLS or implicit TLS with full certificate checks; SASL PLAIN or OAuth. Client adapted from Mailoo by Bitfloo. - Local rules for providers without Sieve:
list_local_rules,add_local_rule,remove_local_rule. Match on from, to, subject or header; move, label, flag, mark read, or forward. They run in the watcher while IMAP Wizard runs and are stored inlocal-rules.json. - Config:
[sieve] allowed_redirectsand per-account[accounts.sieve](enabled,host,port,tls,starttls), withMCP_EMAIL_SIEVE_*env vars.
Security
- Forwarding by any rule (Sieve
redirect, including:copy; local forward) is allowed only to addresses or domains inallowed_redirects, which a person edits inconfig.toml. No tool writesconfig.toml(enforced by a test) and no argument bypasses the check.notify,report,pipe,executeand targets the scanner cannot read for sure are blocked the same way. Included scripts are fetched and scanned too. - Local forwards never send mail from the account itself or from the forward target, to prevent loops.
Install: npx -y imap-wizard, or docker pull ghcr.io/fe2-o3/imap-wizard:v0.3.5
v0.3.4
Added
- Attach local files by path:
send_email,reply_email,forward_emailandsave_draftacceptpathnext tobase64(reply_emailandforward_emailtake attachments for the first time). Reads are guarded: absolute paths and regular files only; hidden files and folders (~/.ssh,.env), system folders,~/Libraryand this app's own folders are refused, symlinks resolved first. Adapted from Mailoo by Bitfloo. dryRun: trueon 11 write tools (send, reply, forward,send_draft, move, delete,bulk_action, create/rename/delete mailbox,delete_label) validates everything and reports what would happen, without writing. Pattern from Mailoo by Bitfloo.- One background writer per machine: with several server processes running, only one runs the watcher, alerts and AI triage; another takes over if it dies (process gone) or hangs (no heartbeat for 120 s). Adapted from Mailoo by Bitfloo.
coretoolset now includesdelete_label,bulk_actionandget_email_status(24 tools; 10 in read-only).
Fixed
get_verification_codemarks email-derived text as untrusted content.- The
bccfield ofsend_emailandsave_draftwas described as CC recipients.
Docs
- Sieve plan updated with the owner's decisions: Sieve and local rules ship together; forwarding only to a config-file allowlist that no tool can change.
Install: npx -y imap-wizard, or docker pull ghcr.io/fe2-o3/imap-wizard:v0.3.4
v0.3.3
Added
settings.toolset("full"default,"core","minimal"; envMCP_EMAIL_TOOLSET) sends the model a shorter tool list: 8 tools in minimal, 21 in core. Prompts and resources stay in every toolset. Grouping idea from Mailoo by Bitfloo.export_emailsaves a message's raw source as a.emlfile (or returns it inline up to 5 MB). Reads withBODY.PEEK, so it never marks mail read. Tool shape from Mailoo by Bitfloo.- Output schemas and structured results for
get_email,get_emails,get_threadandlist_accounts, so clients that generate typed tool libraries ("code mode") work better. - Releases publish themselves: pushing a version tag runs
.github/workflows/release.yml, which publishes to npm (trusted publishing with provenance), the MCP Registry, a multi-arch Docker image atghcr.io/fe2-o3/imap-wizard, and the GitHub release.
Security
- Email text in tool output (
get_email,get_emails,get_thread, list and search previews) is wrapped in untrusted-content markers so a message cannot pass itself off as instructions. Structured results stay raw. Adapted from Mailoo by Bitfloo. download_attachment'ssavePathno longer overwrites existing files or accepts relative paths. Saved files (attachments, exports,saveEmailAttachments) are refused in system folders, hidden folders, the home folder root and this app's own folders, including through symlinks. Path guard adapted from Mailoo by Bitfloo.delete_mailboxandrename_mailboxrefuse INBOX and special-use folders (Sent, Drafts, Trash, Junk, Archive). Adapted from Mailoo by Bitfloo.- Tool annotations are honest:
download_attachmentandexport_email(write local files) andget_emailwithmarkReadare no longer marked read-only. They remain available in read-only mode as before.
Fixed
- Waiting for a mailbox lock is bounded at 60 seconds; a stuck connection is closed and redialled instead of freezing later calls. Adapted from Mailoo by Bitfloo.
- Read-only mode now closes IMAP connections and the cache on shutdown, like write mode.
Changed
- Node.js 22.13 or newer is supported (was 24+).
- Removed the unused GoReleaser configuration.
Docs
docs/dev/sieve-plan.md: plan for server-side filter rules (Sieve), including which providers support it.
Install: npx -y imap-wizard, or docker pull ghcr.io/fe2-o3/imap-wizard:v0.3.3
v0.3.2 — safety guards, reply fixes
Security
- Behavior change: an account whose IMAP or SMTP has
tls = falseandstarttls = falseto a non-loopback host is now rejected when the config loads, and byimap-wizard config validate. The login would cross the network in clear text. To fix a config that stops loading, settls = trueorstarttls = trueon the named[accounts.imap]/[accounts.smtp]section.localhost,127.0.0.0/8and::1stay allowed. Adapted from Mailoo by Bitfloo. - A refused login still shows the server's own reason (for example "application-specific password required"), with any secret it quotes scrubbed.
- Error text from IMAP and SMTP connects, sends, connection tests, the watcher and the OAuth2 token endpoint now has the account's password, OAuth2 tokens and client secret replaced with
[redacted]before it is returned or logged. Adapted from Mailoo by Bitfloo.
Added
NOTICEfile with fork and attribution details; code adapted from Mailoo by Bitfloo (LGPL-3.0-or-later) is credited there and in file headers.- A baseline test locks the registered tools, prompts and resources (names and schemas) in full and read-only mode, so accidental public API changes fail CI. Approach from Mailoo by Bitfloo.
Fixed
- Replies and forwards no longer stack prefixes:
RE:,re:,AW:,SV:,FW:andWG:are recognised in any case (upstream #102). - Sent copies and drafts are normalised to CRLF before IMAP APPEND, so strict servers accept them (upstream #116).
Docs
- The upstream section now shows upstream's own status for each issue as of v0.6.0, instead of implying all are still unfixed there.
Install: npx -y imap-wizard
v0.3.1 — MCP Registry listing, dependency security updates
Fixed
- MCP registry name is
io.github.Fe2-O3/imap-wizard, matching the GitHub owner's case; the registry rejects the lowercase form. - Dependencies updated: no known advisories in production dependencies (
pnpm audit --prod). - Docker images build again (lifecycle scripts skipped during install; overrides file copied).
Install: npx -y imap-wizard. Listed in the MCP Registry as io.github.Fe2-O3/imap-wizard.
v0.3.0 — published to npm as imap-wizard
First npm release of this fork. 0.2.x is skipped because tags v0.2.0–v0.2.3
from the original project's history already exist in this repository.
Added
- Body cache for
get_email(opt-in,settings.cache.read_through, default off) — a message's body, headers and structure are immutable per (UIDVALIDITY, UID), so a repeat read costs a mailbox lock, oneUID FETCH (UID FLAGS)and a local read; flags stay live and a moved or deleted message still reports not found. Live and cached reads build the result with the sameassembleEmail(). Schema v2 adds themessage_bodytable; bodies over 256 KB are skipped rather than truncated, and a decoder version invalidates stale rows. - Offline reads (
offline_reads, default on whenread_throughis on) — when the server is unreachable, an already-cached message is returned with a visible warning. Only genuine connectivity errors qualify; auth failures and not-found are never served from cache. - Bounded body backfill and budget (
body_messages,body_max_mb) — the newest mirrored messages are cached in the background one mailbox lock per message; cached bodies are LRU-evicted pastbody_max_mb, and themax_size_mbbackstop evicts bodies before pruning message rows.
Fixed
- FTS reindex on flag-only resyncs — the
message_fts_updatetrigger fired on every update, rewriting the index for subject, sender and body on each flag change; it now fires only when an indexed column's value changes (migrated automatically on first open). - Mirror rows keyed by the sanitized mailbox name, matching how reads look them up.
Changed
- BREAKING: renamed to
imap-wizard. The npm package isimap-wizardand the command isimap-wizard, replacingemail-mcp. Theinstallwizard'snpx,pnpm dlxand global options no longer launch upstream's@codefuturist/email-mcp; smithery.yaml and server.json point at this fork too. The config, data and cache directories (~/.config/email-mcpand friends), the keychain entries, theEMAIL_MCP_*environment variables and theemailkey written into MCP client configs are unchanged, so existing setups keep working. - Idle exit now defaults to off —
settings.idle_exitdefault 1800 s → 0. The client closing stdin remains the primary exit signal, so a clean Claude/OpenCode quit still ends the server immediately; the timer is now an opt-in backstop (idle_exit = <seconds>orMCP_EMAIL_IDLE_EXIT). New configs and the config template shipidle_exit = 0. - Provider-aware outbound attachment caps —
settings.send.max_attachment_mbdefaults to 25 MB; known provider limits can lower it, and an account-levelmax_attachment_mbcan override it. The cap is checked before SMTP send, including inline and forwarded/draft attachments. - Opt-in verification lookup —
get_verification_codeis registered only whensettings.verification.enabled = true. It scans recent mail only on request; optional magic-link lookup and clipboard writes are off unless explicitly enabled/requested. The clipboard is never read or cleared, and writes are blocked in read-only mode and limited to 10 per minute. - Email terminal CLI — list, read, search, mailboxes, flag, delete, attachment download, reply, and send commands reuse the IMAP/SMTP services and enforce read-only and attachment-size limits.
Install: npx -y imap-wizard (npm: https://www.npmjs.com/package/imap-wizard)
v0.1.0 — hardened fork, first release
84 commits past the fork point. Every fix links the upstream issue it closes — all 17 were verified still open after upstream's v0.5.1.
Highlights
- All 17 open critical bugs fixed — sent-mail filing, attachments on send, disk saves, llama.cpp-safe schemas, date ordering, multipart bodies, duplicate-send guard, orphan-process leak, the 6-day OOM, and more. Full table in What's Fixed.
- 13 security hardening controls — header injection, timing attacks, private-IP SSRF, HTTPS-only OAuth, loopback token requirement, owner-only credential files, bounded request bodies, and a disclosure policy in SECURITY.md.
- Large mailboxes work — UID fetches chunked at 400 per command; list/search/stats verified on a 64,779-message Hostinger mailbox.
- No orphan processes — exits when the client closes stdin, plus
settings.idle_exit(default 30 min,0disables). - macOS Keychain +
password_command— no plaintext passwords at rest (1Password, Bitwarden, pass, any shell command).
Ported from upstream v0.5.1
Credit where due — three wins from the upstream release train of 2026-09-26 were adopted instead of left as gaps:
| Ported | Upstream commit | Why |
|---|---|---|
TLS servername repair for IP-literal hosts |
70d4215 |
Every IMAP login to an IP address died before auth — shared bug, fixed in all three construction sites via createImapClient() |
config validate |
bf09dcc |
Syntax, schema, did-you-mean typo detection, consistency checks; exit 1 on errors |
| Dependency set (v0.4.1 line) | bae1bb7 |
imapflow 2, nodemailer 10, vitest 5, zod 4.6, @clack/prompts 1.8 — with type adaptations, full suite green |
The rest of the upstream v0.5 line (OTP catcher, HTTP daemon lifecycle, shell completion, bun binaries) is drafted — not silently skipped — in docs/upstream-v0.5-draft.md.
Verification
pnpm typecheck clean
pnpm test 428/428 passed (55 files)
pnpm build clean
pnpm check biome clean (161 files)
config validate real user config → exit 0; typo/exit-1 path proven on a temp config
Install
git clone https://github.com/Fe2-O3/email-mcp.git
cd email-mcp
pnpm install && pnpm build
node dist/main.js account add
Client setup (Claude Desktop/Code, Cursor, VS Code, Codex, OpenCode with timeout: 180000, Streamable HTTP) is in the README.
Notes
- Full changelog: CHANGELOG.md
- Upstream's own releases (v0.1.0 → v0.5.1) remain at codefuturist/email-mcp/releases. This repository's
v0.1.0tag starts the fork's own version line (the package was frozen at upstream's dev version0.3.0before this release); an inherited copy of upstream's ancient v0.1.0 tag was replaced to make room.