mail-mcp
Built on davidvornholt/standards.
A draft-only IMAP helper for Thunderbird workflows, exposed to Codex, Claude, and other compatible clients as an MCP server and to you as a mail CLI over one shared Effect core. Through the MCP server it can search and read mail and create, update, or delete drafts with HTML and attachments; the mail CLI covers login, status, folder/search/read, and plain-text draft creation. It cannot send emails: drafts sync into Thunderbird for review and sending.
Layout
apps/mail the application (MCP server + CLI)
src/app entrypoints: server.ts (MCP, stdio), cli.ts (the `mail` bin)
src/features/mail schemas, tagged errors, and Effect services (config, secrets, status, IMAP, draft, login)
src/shared app-local infrastructure (arg parsing, hidden-input terminal prompt)
packages/* canonical shared config synced from the standards template
See apps/mail/README.md for the tool list, configuration, and secret handling.
Setup
bun install
# put the `mail` command on your PATH (one-time; links the app's bin into
# ~/.bun/bin). After this, run `mail …` from anywhere.
bun link --cwd apps/mail
# configure your accounts (non-secret: addresses, IMAP hosts, and ports). The real
# file is git-ignored so your addresses never land in git.
cp apps/mail/accounts.example.toml apps/mail/accounts.toml
# …edit apps/mail/accounts.toml…
# verify each account's password against IMAP, then store it in the OS keyring
# (hidden prompt — nothing is echoed or written to disk). Run this yourself;
# the secret never leaves your machine.
mail login [email protected]
# confirm each account authenticates cleanly (or shows what still needs a login)
mail status
Register the MCP server with Codex:
codex mcp add mail -- bun run <repo>/apps/mail/src/app/server.ts
codex mcp get mail
Codex defers MCP tool definitions until they are relevant, so registering theserver does not eagerly add every mail tool schema to the model context. RestartCodex after adding it, then use /mcp to inspect the connected server.
For explicit write approvals and more headroom for IMAP operations, edit thegenerated entry in ~/.codex/config.toml:
[mcp_servers.mail]
command = "bun"
args = ["run", "<repo>/apps/mail/src/app/server.ts"]
startup_timeout_sec = 15
tool_timeout_sec = 120
default_tools_approval_mode = "writes"
[mcp_servers.mail.tools.delete_draft]
approval_mode = "prompt"
For Claude Code (user scope), use:
claude mcp add --scope user mail -- bun run <repo>/apps/mail/src/app/server.ts
Once a password is stored, ask your MCP client to search your mail or compose a draft. You can also drive the review-first CLI yourself:
mail search [email protected] invoice
Not ready to link a global command? Every example also works as bun run apps/mail/src/app/cli.ts <args>.
Requirements
- Bun (see
packageManagerinpackage.json). - A running, unlocked Secret Service provider (gnome-keyring) for the OS keyring.
Quality gate
bun run check runs the standards drift check, then lint, type-check, tests, build, and a11y across every workspace. It must pass before a change is done.
