email-mcp
Provides an optional Agent Chat add-on and MCP bridge for Thunderbird, enabling a local LLM agent to exchange chat messages through a token-protected local listener without accessing email or modifying Thunderbird's native chat interface.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Thoth is a desktop workspace built on Thunderbird: mail, calendar and tasks,
a document editor, slides, drawing, notes, a browser and a terminal, with an
AI agent that works in all of them through MCP. This repository holds the
app (the thunderbird-addon/ folder), its MCP servers and the setup around
email-mcp.
email-mcp gives an MCP-compatible AI client access to a mailbox over IMAP and SMTP, independently of the app. Nothing here copies a Thunderbird profile or changes Thunderbird itself; Thoth runs as an add-on.
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.
Thoth itself, installed into Thunderbird as an add-on: chat and file docks, a file viewer, artifacts, paint, and agent control of the GUI, connected through listener-mcp.
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: mcp-imap-smtp
Requirements
Linux, macOS or Windows 10/11, with:
Node.js 24 or newer, and Git (npm fetches listener-mcp from GitHub)
An IMAP/SMTP mail account (an app password is recommended when supported)
Thunderbird 140 or newer, installed separately, if you want a graphical mail client
Optional programs, each used for one part of the workspace:
Program | Used for | Linux | macOS | Windows |
LibreOffice | viewing Word and PowerPoint files | package manager |
|
|
Inkscape | Draw: path operations, PDF and PNG export | package manager |
|
|
Quarto | Writer: rendering documents | package manager |
|
|
Tesseract | PDF: recognizing text in scans (OCR) |
|
|
|
LanguageTool (Java) | Writer: grammar checks | package manager |
| unpack the download, set |
They are found on PATH or where their installers put them (the app bundle on
macOS, Program Files on Windows). MAIL_WORKSPACE_INKSCAPE,
MAIL_WORKSPACE_SOFFICE, MAIL_WORKSPACE_TESSERACT and QUARTO point at a
program anywhere else. LibreOffice also lets the PDF space create a PDF from a
Word file.
On Windows, run the commands below in PowerShell (or Git Bash), in a normal
terminal window. Not in a terminal that runs inside a packaged (MSIX) app,
such as the Claude desktop app's terminal: Windows keeps what such an app
creates in %APPDATA% and %LOCALAPPDATA% private to it
(%LOCALAPPDATA%\Packages\<app>\LocalCache), so Thunderbird, the logon
tasks and the taskbar would not see Thoth's profile, listener-mcp's tokens
or the settings. npm run thoth:install and npm run services:install
check this and stop with that message. An agent in such an app can still
use Thoth afterwards; it only must not do the setup.
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 # Linux and macOS
npm run verifynpm 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_gui]
command = "node"
args = ["/absolute/path/to/mail-mcp-workspace/src/gui-main.mjs"]For Claude Code, register the same servers in user scope, so agents started in any directory have them. On any system:
node scripts/register-mcp.mjs # --remove takes them out againor by hand (bash):
repo=/absolute/path/to/mail-mcp-workspace
claude mcp add-json --scope user email "{\"command\":\"$repo/node_modules/.bin/email-mcp\",\"args\":[\"stdio\"]}"
claude mcp add-json --scope user mail-workflow "{\"command\":\"node\",\"args\":[\"$repo/src/main.mjs\",\"stdio\"]}"
claude mcp add-json --scope user mail-attachments "{\"command\":\"node\",\"args\":[\"$repo/src/attachments-main.mjs\",\"stdio\"]}"
claude mcp add-json --scope user mail-gui "{\"command\":\"node\",\"args\":[\"$repo/src/gui-main.mjs\"]}"Agent Chat's MCP server (listener) is added for every agent session by
listener-mcp init --user; see
Thoth for Thunderbird.
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 services:install -- --watch personal --every 60 # run the watcher at loginStart 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"]npm run services:status shows it. The service is a systemd user unit
mail-mcp-workflow-watcher.service on Linux, the launchd agent
dev.mail-workspace.watcher on macOS, and the logon task
mail-mcp-workflow-watcher on Windows; its log is watcher.log in the
workspace's state folder (see Files on each system).
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, handles and stops the Agent Chat conversation.
listener is listener-mcp's general skill for receiving app events.
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.
Thoth for Thunderbird
Thoth is an optional Thunderbird add-on (in thunderbird-addon/)
that turns Thunderbird into a workspace built around your agent.
One window, no tab bar, no top bar. You navigate with the spaces sidebar: Mail, Address Book, Calendar, Tasks, Files, Artifacts and Paint. Double-clicking a message shows it in the message pane instead of a new window. Ctrl+F opens a floating search box.
Panels never overlap. Widening a dock minimizes other panels (the other dock, Today pane, folder pane, message pane) and restores them as you shrink it again. When there is nothing left to minimize, the dock stops growing.
Chat dock (right, open by default). Drag to resize, minimize to a rail, or maximize. It stays visible in every space. Ctrl+5.
File browser dock (left, minimized by default). Toggle it from the spaces sidebar. Click any part of the path to go up, or type a path. It shows a VS Code-style tree with Material Icon Theme icons. Ctrl+6.
Files space: a read-only viewer. It shows:
PDF;
Word, ODT, PowerPoint and ODP (converted to PDF with LibreOffice);
Excel, ODS and CSV;
markdown, and code (Shiki, about 300 languages) or text;
images, GIF and SVG;
audio (with a waveform) and video.
Artifacts space. React apps the agent builds for you, stored in
~/Artifacts, with the library on the left:they're organised in a folder tree you can collapse, and reload live when their files change;
they're sandboxed: running commands, calling local HTTP services and touching files each need a permission that you approve per artifact.
Paint space. Paste a screenshot, mark it up, and use Send to agent. It has rectangle, lasso and polygon selection (cut, copy, delete, move), a resizable canvas, and the usual paint shortcuts while it has focus (? lists them).
Writer space. A word processor for papers in Quarto (
.qmd,.md), laid out like ONLYOFFICE's document editor: ribbon tabs, rulers, the document on sheets of its paper, side panels and a status bar.File: create, open, save, a copy, print, Info (title, authors, date, abstract and the Quarto header) and Download As: DOCX, PDF, ODT, MD, RTF, TXT, FB2, EPUB and HTML, through Quarto.
Home: font, size, case, bold to subscript, highlight and font colours, lists, indents, alignment, line spacing, formatting marks, the style gallery, and Find and Replace (Ctrl+F/H).
Insert: page breaks, tables, images, comments, links, the date, equations and symbols.
Layout: margins, orientation, size, columns, line numbers (continuous or per page) and the paragraph's indents and spacing. The rulers drag margins and indents.
References: table of contents, footnotes, bookmarks, cross-references, citations and the bibliography. Citations and cross-references read as in the PDF: "(Smith and Jones 2020)", "Figure 2".
Collaboration: comments, track changes (kept in Pandoc's form, so the Word export has them as Word's own), display modes, accept and reject, "Review with agent" and spell checking (LanguageTool).
View: headings, zoom and fit, and which bars show.
A document without its own page settings is set as Word sets a new one (A4, 2.5 cm margins, 12 pt Times New Roman or a metric twin), on the page and in the PDF and Word file alike. Formatting Markdown has no syntax for is written the Pandoc way (
[text]{.underline},[text]{style="color: #C00000"},::: {style="text-align: center"}), which the exports honour; untouched paragraphs are saved byte for byte.
PDF space. A PDF editor like Acrobat, on MuPDF, laid out as the Writer is; .pdf files open in it (Ctrl+Shift+0). Edits stay in the document, with undo, until you save.
File: create a PDF from a blank page, by combining files, from a Word file or from images; open, recent files, Save As, Download As (PDF, Word, Excel, PNG, JPEG, text), print and the document's properties.
Home and View: zoom and fit, one or two pages, rotation, thumbnails, bookmarks and search with results in context.
Comment: sticky notes, text boxes, highlight, underline, strike-out, drawing, shapes, arrows and stamps, with replies and status in a comments panel.
Fill & Sign: form fields filled in place, ticks, crosses, dates, and a signature typed, drawn or from an image; flatten.
Pages: reorder by dragging thumbnails, insert pages or files, delete, rotate, duplicate, crop, extract and split.
Edit: change the document's own text and images in place, keeping the paragraph's font, size and colour; add text and images.
Protect: true redaction (what is under the marks is removed from the file), passwords and permissions (AES-256), sanitizing.
Tools: recognize text in scans (Tesseract), compress, export to Word and Excel, and compare two versions.
Terminal. Ctrl+` slides a terminal up over the window, with tabs and horizontal or vertical splits. The agent can open terminals and run commands in them; you see everything it types.
Agent control. Through the
mail-guiMCP server, the agent sees what's selected, opens spaces and files, and clicks or types anywhere in the GUI. Sending, deleting, moving mail and changing settings ask you first, in the chat.Redesign. Material Symbols icons, styled tooltips, and a System, Light or Dark appearance applied to Thunderbird's own UI. The settings page also picks the code viewer's theme from 15 popular ones (One Dark Pro by default).
Parts:
Part | What it is |
| The add-on: an Experiment API for the layout, theme and automation, plus the pages for chat, files, viewer, artifacts and paint |
| Workspace host on |
|
|
Local broker the add-on and agents talk through (chat on |
Set it up on each machine:
npm install -g --allow-git=root github:1101AlexZab1011/listener-mcp
listener-mcp service install # the broker, started at login
npm ci # add-on and host dependencies
npm run services:install # the workspace host, started at login
listener-mcp init --user --agent claude,codex # listener MCP server, hooks and skill for every session
listener-mcp app add mail --credential email-agent --group "mail-chat-{instance}" --channels "mail/chat/{instance},mail/replies/{instance}/**" --from now --exclusive --single-instance
listener-mcp token create --name mail-watcher --scopes "publish:mail/replies/**,read:mail/chat/sessions" --save # reply announcements
npm run thoth:install # Thoth itself: its profile, the add-on, and a "Thoth" app entry; starts itThoth runs in Thunderbird, in a profile of its own, so starting Thoth always
opens Thoth and a Thunderbird you already use stays as it was.
npm run thoth:install (Thunderbird must be installed first):
creates the profile (
~/.local/share/thoth,~/Library/Application Support/Thothor%APPDATA%\Thoth) with the add-on installed and enabled, and without Thunderbird's start page, What's New, donation and default-client prompts or data collection;pairs the add-on with listener-mcp, so the chat works on the first start;
adds Thoth where you start apps, with its icon: the app menu on Linux, the Start menu and the desktop on Windows,
~/Applications/Thoth.appon macOS. Thoth's windows carry its icon too.
Start it from there, or with npm run thoth. Running thoth:install again
updates the add-on and keeps your profile; npm run thoth:uninstall removes
the app entry (-- --purge also deletes the profile with its accounts and
local mail). Thoth updates itself afterwards (Settings → Updates).
The commands are the same on every system. service install and
services:install set up per-user services: systemd user units on Linux,
launchd agents on macOS, logon tasks on Windows (they run hidden, and restart
after a failure).
Agent Chat holds several sessions, each its own conversation with its own agent. Click the agent icon in the chat header to switch, rename, delete or create one. A new session is called "Agent N" (the lowest free N) and opens with its name selected, so you can type the real one at once. Agent 1 can be renamed but not deleted.
app add registers mail as the app mail with one listener group per session
({instance} is the session id), so a session in any directory can start
Agent Chat. Each session holds one agent, and an agent holds one session:
/email-start-chat Presentations attaches it there, or moves it if it was in
another session. Reply and mail-watch notifications go to the session that set
them up. To make the skills available outside this repository, link them into
your user skill folders:
for skill in email-start-chat email-compose email-review-pending email-summary mail-workspace; do
ln -sfn "$PWD/skills/$skill" ~/.claude/skills/$skill
ln -sfn "$PWD/skills/$skill" ~/.agents/skills/$skill # Codex
doneOn Windows (PowerShell), junctions need no administrator rights:
foreach ($skill in "email-start-chat","email-compose","email-review-pending","email-summary","mail-workspace") {
New-Item -ItemType Junction -Force -Path "$HOME\.claude\skills\$skill" -Target "$PWD\skills\$skill"
}If the chat says it is not paired (the pairing waits ten minutes for Thoth's
first start), open Settings → Agent connection, run the listener-mcp pair …
command it shows, and press Pair now.
For GUI control, the agent's credential also needs the GUI and workspace
scopes. The command replaces the credential app add made, so it repeats
that one's chat and reply scopes (without mail/replies, attaching fails
with "may not subscribe on mail/replies/…"):
listener-mcp token create --name email-agent --replace --save --scopes "subscribe:mail/chat/**,publish:mail/chat/**,read:mail/chat/**,subscribe:mail/replies/**,publish:mail/replies/**,read:mail/replies/**,publish:mail/gui/commands,read:mail/gui/**,read:mail/workspace/files,publish:mail/workspace/fs,publish:mail/workspace/render,publish:mail/workspace/artifacts,read:mail/workspace/artifacts,publish:mail/workspace/terminal,blobs"The agent's token deliberately lacks publish:mail/workspace/grants and
…/capabilities. It can write an artifact, but only you can allow what the
artifact may do.
With publish:mail/workspace/fs the agent writes, edits, moves and creates
files and folders anywhere in your home folder, except credential folders
such as ~/.ssh and ~/.gnupg. Writes are atomic and refuse to overwrite a
file that changed since it was read. Trashing needs
publish:mail/workspace/fs-trash, which only the add-on has, so the agent's
files_trash always asks you in the chat first.
Files on each system
What | Linux | macOS | Windows |
Mail accounts (email-mcp) |
|
|
|
Workflow policy and state |
|
|
|
Workspace settings, grants, logs, editor backups |
|
|
|
Workspace cache |
|
|
|
listener-mcp tokens |
|
|
|
What else differs:
Trash. Deleting goes to the system's Trash: the freedesktop Trash, the macOS Trash, or the Recycle Bin. Restoring works from the workspace and from the file manager.
Shells. The terminal opens your login shell; on Windows, PowerShell 7 if it is installed, else Windows PowerShell (
MAIL_WORKSPACE_SHELLpicks another). Artifact commands run in bash, and in PowerShell on Windows (MAIL_WORKSPACE_EXEC_SHELL=bashuses Git Bash there).Shortcuts. On macOS, ⌘ replaces Ctrl in the workspace's shortcuts, and the hints say so. Ctrl+
</kbd> stays the terminal, since <kbd>⌘</kbd>+<kbd>switches windows.
To start chatting, run /email-start-chat <session name> in Claude Code or
Codex, in any directory (restart the agent after init --user). The mail-workspace skill teaches the agent the GUI
tools. Disabling the add-on restores Thunderbird's own layout, tab bar and
look.
Development (Linux). Start Thunderbird with node scripts/tb.mjs restart (it
enables Marionette), then:
node scripts/tb.mjs installloads the add-on from its folder;node scripts/tb.mjs shot out.pngtakes a screenshot;node scripts/gui.mjs statesends GUI commands the way the agent does.
node scripts/build-icons.mjs and node scripts/vendor.mjs regenerate the
icon set and the vendored PDF.js and xterm.js. tb.mjs starts Thunderbird with
--class Firefox (override with TB_WM_CLASS) so a window-manager rule can
keep it on its own workspace.
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:addon # build the Thunderbird add-on package
listener-mcp status 'mail/chat/**' # who is listening to Agent Chat
npm test # run local workflow testsPrivacy 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's tokens and conversation history belong to listener-mcp and live outside the repository (see Files on each system).
The broker binds only to
127.0.0.1and checks theHostheader.Every request needs a token, scoped here to
mail/chat/**.The add-on's token works only from the add-on's own origin.
The chat tools only exchange chat events: they can't 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.
The PDF space uses MuPDF (mupdf.js), vendored into thunderbird-addon/vendor/mupdf/, under its AGPL-3.0 licence (vendor/mupdf/LICENSE).
The Slides editor in slides/ is a fork of PPTist and stays under its AGPL-3.0 licence (slides/LICENSE); so does its build, vendored into thunderbird-addon/vendor/slides/.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Give AI agents their own email inboxes: list, read and send mail via scoped, revocable OAuth grants.
Real email inboxes for AI agents: register, receive, read and send mail over MCP. Free to receive.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceConnects any IMAP/SMTP mailbox to AI agents via MCP, enabling email read, search, send, reply, and management through natural language.11 npmMIT
- AlicenseNot gradedqualityCmaintenanceConnects MCP-compatible AI assistants to any IMAP/SMTP mailbox, enabling email search, reading, folder management, and sending with automatic saving to Sent.1MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to manage multiple email accounts, including searching, reading, sending, replying to, forwarding, organizing, and bulk-deleting messages across IMAP/SMTP, with encrypted credential storage and connection pooling.1,009 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to securely connect to one or more email accounts over IMAP and SMTP, so they can search, read, send, reply to, forward, move, mark, and bulk-delete messages and manage folders across multiple mailboxes. Credentials are stored encrypted with AES-256 and can be supplied at runtime via environment variables.1,009 npmMIT