# mail-mcp

> Built on [davidvornholt/standards](https://github.com/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 received attachments, create, update, or delete drafts with HTML and attachments, and tag existing drafts in batches; 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`](apps/mail/README.md) for the tool list, configuration, and secret handling.

## Setup

```bash
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 every account's password against IMAP, then store each in the OS keyring
# (hidden prompts — nothing is echoed or written to disk). Run this yourself;
# the secrets never leave your machine.
mail login

# confirm each account authenticates cleanly (or shows what still needs a login)
mail status
```

Register the MCP server with Codex:

```bash
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 the
server does not eagerly add every mail tool schema to the model context. Restart
Codex after adding it, then use `/mcp` to inspect the connected server.

For explicit write approvals and more headroom for IMAP operations, edit the
generated entry in `~/.codex/config.toml`:

```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:

```bash
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:

```bash
mail search invoice
mail search --account you@example.com invoice
```

Omitting `--account` searches every configured account, merges and deduplicates the results, and applies the limit globally. Pass `--account <email>` to search only that account. Each result includes its account handle, and failures from individual accounts are reported alongside partial results. If every account fails, the command fails with all account errors.

Folder searches are account-specific: use `mail search --account you@example.com --scope folder --folder INBOX ...` for one exact folder or `--scope subtree --folder Projects` for a folder and its descendants.

Not ready to link a global command? Every example also works as `bun run apps/mail/src/app/cli.ts <args>`.

## Requirements

- Bun (see `packageManager` in `package.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.