Mail MCP Workspace

A portable, local setup for email-mcp and Thunderbird.

email-mcp gives an MCP-compatible AI client access to a mailbox over IMAP and SMTP. Thunderbird is a separate desktop client for the same mailbox. This repository does not modify Thunderbird, copy a Thunderbird profile, or connect to Thunderbird directly.

What is included

• A version-pinned local installation of @codefuturist/email-mcp.

• mail-workflow-mcp, an optional provider-neutral IMAP workflow server.

• Commands to configure, verify, and run the MCP server.

• Portable skills for Pending-mail review and chronological email summaries.

• An optional local-only Agent Chat Thunderbird add-on and MCP bridge.

• Documentation for setting up the same mailbox on another machine.

No account details, server addresses, passwords, OAuth tokens, or Thunderbird profiles are stored here.

Related MCP server: Mail-MCP

Requirements

• Node.js 24 or newer

• An IMAP/SMTP mail account (an app password is recommended when supported)

• Thunderbird, installed separately, if you want a graphical mail client

Install on another machine

git clone https://github.com/YOUR-GITHUB-USER/mail-mcp-workspace.git
cd mail-mcp-workspace
npm ci
npm run configure
chmod 600 ~/.config/email-mcp/config.toml
npm run verify

npm run configure opens the upstream interactive setup wizard. It discovers or asks for your account's IMAP/SMTP settings and writes credentials only to ~/.config/email-mcp/config.toml on that machine.

Add the same account independently in Thunderbird using its account setup screen. Thunderbird keeps its own profile and credentials; they are not needed by this repository.

Connect an MCP client

Use the locally installed, locked dependency in your MCP client's user-level configuration. Replace /absolute/path/to/mail-mcp-workspace with this clone's actual path:

[mcp_servers.email]
command = "/absolute/path/to/mail-mcp-workspace/node_modules/.bin/email-mcp"
args = ["stdio"]

[mcp_servers.mail_workflow]
command = "node"
args = ["/absolute/path/to/mail-mcp-workspace/src/main.mjs", "stdio"]

[mcp_servers.mail_attachments]
command = "node"
args = ["/absolute/path/to/mail-mcp-workspace/src/attachments-main.mjs"]

[mcp_servers.mail_agent_chat]
command = "node"
args = ["/absolute/path/to/mail-mcp-workspace/src/chat-main.mjs", "stdio"]

For Codex, add both blocks to ~/.codex/config.toml. Restart the client after editing its configuration. Other MCP clients use the same command and argument in their equivalent user configuration.

Workflow automation

The optional workflow MCP server is provider-neutral: it uses IMAP and the existing local email-mcp account configuration, but keeps its policy and state outside this repository.

npm run workflow:init              # create ~/.config/mail-mcp-workspace/policy.toml
npm run workflow:sync -- personal  # preview routing, status classification, and filing
npm run workflow:sync -- personal --apply
npm run workflow:watch -- personal 300 --apply
npm run workflow:install-watcher -- personal 60 # install/start a systemd user service

Start with the generated policy's review mode. The supported filing modes are review, propose, existing-folders, and managed-groups; the last two are explicit opt-ins. In existing-folders mode, only allowlisted Active folders can receive automatic moves. New groups require managed-groups plus allow_new_groups = true. Every move is recorded in a local action journal and can be undone with the undo_last_workflow_action MCP tool.

For accounts with provider-side filtering, leave routing_mode = "provider". For a generic IMAP fallback, choose routing_mode = "watcher" and configure account-local subject rules. Never enable both routing mechanisms for one account at the same time.

The installed watcher polls every 60 seconds by default. Its first live run stores a per-folder UID baseline and never copies existing mail. Later runs copy only newly delivered mail from INBOX and other eligible delivery folders (for example, Additional or Important) into Pending/<group>, preserving the original delivery in its source folder. The original is marked read and the Pending copy is unread. It never watches Active, Archived, Drafts, Junk, Pending, Sent, or Trash. To use a strict source allowlist instead, set it in the account policy:

[accounts.personal]
routing_mode = "watcher"
routing_source_mailboxes = ["INBOX", "Additional", "Important"]

The service is named mail-mcp-workflow-watcher.service; manage it with systemctl --user status|stop|restart mail-mcp-workflow-watcher.service.

mail-workflow-mcp currently supports password-authenticated IMAP accounts configured by email-mcp. Providers requiring OAuth-only access need an upstream email-mcp OAuth extension before this workflow process can connect directly.

Agent skills

• email-review-pending reviews pending mail, reports urgent items, and files only non-urgent mail when policy allows.

• email-summary summarizes received mail from the requested number of days in chronological order.

• email-start-chat starts and handles a separate local Agent Chat conversation.

Copy a skill directory into the skill location used by Codex, Claude Code, or another SKILL.md-compatible agent. The agent must also have access to the email and workflow MCP servers above.

Agent Chat for Thunderbird

Agent Chat is an optional local conversation window for an LLM agent. It is not email and it has no access to your messages, folders, or sending identity. The Thunderbird add-on sends chat text only to a token-protected listener on 127.0.0.1; the compatible agent reads and replies through mail_agent_chat.

Set it up on each machine:

npm run chat:init
npm run chat:install-service
npm run chat:addon

The first command creates ~/.config/mail-mcp-workspace/agent-chat.json with a private random token. Open that file locally and copy its host, port, and token into the Agent Chat add-on's Settings page. Do not put this file or its token in Git, screenshots, prompts, or chat messages.

Install dist/agent-chat.xpi in Thunderbird from Add-ons and Themes → gear menu → Install Add-on From File, then use the Open Agent Chat toolbar button. Thunderbird's native Chat feature is not patched: supported MailExtension APIs cannot safely replace that built-in view. Agent Chat is a separate tab and disabling or removing the add-on restores ordinary Thunderbird behaviour.

Copy skills/email-start-chat to the skills location of Codex, Claude Code, or another SKILL.md-compatible agent, then restart that agent. Run /email-start-chat to start/check the listener, retrieve queued messages, and reply with send_to_chat. The listener keeps unacknowledged messages if no agent session is active; it does not run an LLM by itself.

The service is managed as mail-mcp-agent-chat.service. To stop it:

systemctl --user stop mail-mcp-agent-chat.service

Stopping it does not delete queued conversations. Local configuration and conversation state reside under ~/.config/mail-mcp-workspace/ and ~/.local/state/mail-mcp-workspace/, respectively, both outside this clone.

Everyday commands

npm run configure  # add or update an account interactively
npm run verify     # test all configured accounts
npm run mcp        # run the MCP server over stdio
npm run workflow:mcp # run the workflow MCP server over stdio
npm run chat:init    # create a local Agent Chat token/configuration
npm run chat:install-service # install/start the local listener service
npm run chat:addon   # build the Thunderbird add-on package
npm test            # run local workflow tests

Privacy and security

Credentials are deliberately kept outside the repository. Do not commit ~/.config/email-mcp/config.toml, a Thunderbird profile, .env files, or MCP client configuration files. The provided .gitignore excludes common local credential files, but always inspect git status before committing.

Agent Chat uses a separate token and local conversation history; those are also outside the repository. The listener binds exclusively to 127.0.0.1 and requires the token for every request. Its MCP send_to_chat tool only appends a chat reply—it cannot send email, modify mail, or execute commands.

This workspace only pins and configures the upstream server; email operations and the credential storage format are implemented by @codefuturist/email-mcp.

npm audit currently reports two high-severity findings inherited from the upstream package's nodemailer dependency (GHSA-p6gq-j5cr-w38f). npm audit fix --dry-run found no available automatic remediation. Review the advisory before using this setup with untrusted message content, and keep the dependency updated.

License

The workspace documentation and configuration files are MIT licensed. The upstream @codefuturist/email-mcp dependency is separately licensed under LGPL-3.0-or-later.