mailroom-mcp

One self-hosted MCP server for your mail, shared by all your AI assistants (Claude, ChatGPT, Codex…). Search, read, sort and draft, with compact answers.

Early. Several IMAP mailboxes, Gmail / Google Workspace included (OAuth). Microsoft 365 is next.

Why

Each AI vendor connects its own mailboxes: one inbox ends up in Claude, another in ChatGPT, and no model sees them all. mailroom-mcp owns the mail access instead. Add a mailbox once, and every assistant can use it.

• Safe by default: reading never marks as read, no permanent deletion, replies are drafts. Sending is off unless you enable it, with a preview and confirmation tied to the exact draft. In code-based confirmation, your assistant must ask for your approval; the server cannot verify that the assistant actually asked you.

• Mail is data, not instructions: the model is told so.

• Light on context: compact JSON, paginated, strict parameters.

Related MCP server: IMAP MCP Server

Quick start

With uv, put your IMAP password in ~/.config/mailroom-mcp/password (mode 600), then:

claude mcp add mail -e MAIL_IMAP_HOST=imap.example.org -e MAIL_USER=me@example.org \
  -- uvx --from git+https://github.com/grodriguez-fr/mailroom-mcp mailroom-mcp

For Codex:

codex mcp add mail --env MAIL_IMAP_HOST=imap.example.org --env MAIL_USER=me@example.org \
  -- uvx --from git+https://github.com/grodriguez-fr/mailroom-mcp mailroom-mcp

Run the server with --check to test the login without reading mail. To reach it from ChatGPT or your phone, run it remotely: docs/deployment.md.

Several mailboxes

Point MAIL_ACCOUNTS_FILE at a JSON list of accounts instead of setting MAIL_IMAP_HOST and MAIL_USER. Relative paths are relative to that file; secrets stay in their own files (mode 600), read on use.

[
  {"name": "perso", "host": "imap.example.org", "user": "me@example.org",
   "aliases": ["me@old-job.example"],
   "auth": {"type": "password", "password_file": "perso.password"}},
  {"name": "work", "user": "me@company.com", "send": true,
   "auth": {"type": "google-oauth", "client_secret_file": "google-client.json",
            "refresh_token_file": "work.token"}}
]

port defaults to 993 and, for google-oauth, host to imap.gmail.com. Names are short slugs ([a-z0-9-]). aliases (optional) lists your other addresses for that mailbox, the ones that forward to it or that you send from: mail to them is addressed to you, mail from them is your own. "send": true (optional, off by default) lets the account send drafts; "smtp": {"host", "port", "security"} (optional, "ssl" or "starttls") overrides the server, which defaults to smtp.gmail.com:465 for Gmail and to the IMAP host on port 465 otherwise. For a Gmail account, create the OAuth client and the refresh token once: docs/google-oauth.md. mailroom-mcp --check then tests every account. Every tool takes an optional account; searches cover all accounts by default.

Tools

list_folders, search_messages (one folder, several or the whole mailbox; unread, awaiting your reply, automated mail apart, by sender…), read_message (clean text, attachments listed), move_messages, set_flags, create_folder, save_draft. Drafts can be sent with send_draft after your explicit approval (two steps: a preview, then a confirmation). Details: docs/tools.md.

Roadmap

1. Microsoft 365 over OAuth.

2. Remote access from Claude connectors, not only ChatGPT.

Development

uv sync && uv run pytest && uv run ruff check src tests

Contributions welcome. Security issues: please use a private GitHub security advisory.

License

MIT