mcp4mail MCP server
Commit Nov 13, 2026Connect an IMAP account to let your AI assistant read, search, and organize your emails via OAuth 2.1.
Also known as jchsoft/mcp4mail
- Stars
- 0
- Tools
- 14
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is mcp4mail MCP?
mcp4mail connects an IMAP account to let your AI assistant read, search, and organize your emails via OAuth 2.1. It exposes 14 tools, such as list_mail_accounts, get_mail_account, list_folders.
Summary generated from the project's README
About mcp4mail MCP server
mcp4mail allows you to connect an IMAP account to an AI assistant using the Model Context Protocol. It enables an AI to read, search, and organize your emails through OAuth 2.1 authorization. You can use the hosted version at mcp4mail.online by adding its MCP endpoint to clients like Claude, ChatGPT, Cursor, or VS Code, or you can self-host the server using Docker to ensure your credentials never leave your own machine.
The server provides 14 specific tools for managing your mailbox. These include searching messages by subject or sender, downloading attachments, and looking up contacts. While the system is read-only by default, you can explicitly grant permission for the AI to perform write actions such as moving messages, creating folders, or saving drafts. To prevent accidental sending, the send_message tool only prepares an email for you to review and send manually. The system includes safety measures like search budgets and rate limits to prevent runaway loops.
What you can do with it
- 1Manage email organizationInstruct the AI to move specific emails into different folders or mark them as read.
- 2Draft and review outgoing mailHave the AI prepare a response to an email that you can then personally approve and send.
Written from the project's README. Every use case is checked against a quote from it.
How to install mcp4mail MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall mcp4mail MCP in Claude Code
$ claude mcp add --transport http mcp4mail https://mcp4mail.online/mcpInstall mcp4mail MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp4mail": {
"url": "https://mcp4mail.online/mcp"
}
}
}Install mcp4mail MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp4mail": {
"type": "http",
"url": "https://mcp4mail.online/mcp"
}
}
}Install mcp4mail MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp4mail","type":"http","url":"https://mcp4mail.online/mcp"}'Install mcp4mail MCP in Codex
$ codex mcp add mcp4mail --url https://mcp4mail.online/mcpInstall mcp4mail MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp4mail] url = "https://mcp4mail.online/mcp"
Install mcp4mail MCP in Gemini CLI
$ gemini mcp add -s user --transport http mcp4mail https://mcp4mail.online/mcpInstall mcp4mail MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp4mail": {
"url": "https://mcp4mail.online/mcp",
"type": "http"
}
}
}mcp4mail MCP tools 14
Detected from the READMElist_mail_accountsget_mail_accountlist_folderssearch_messagesget_messageget_attachmentsearch_contactsget_outgoing_statusset_flagsmove_messagetrash_messagecreate_folder
Show all 14 toolsShow fewer tools
create_draftsend_message
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejchsoft/mcp4mail is public and reachablegithub.com/jchsoft/mcp4mail ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/jchsoft/mcp4mail ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model14 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubmcp4mail
Your mailbox as an MCP server. Connect an IMAP account and let your AI assistant read and search your mail, authorized over OAuth 2.1. Hosted at mcp4mail.online, open source and self-hostable.
Run it yourself and your credentials never leave your machine. A hosted mail connector necessarily keeps
your IMAP password on someone else's server; with mcp4mail you can keep it in your own database instead. One
docker compose up gets you there: see the self-hosting guide.
mcp4mail is young, and we use it ourselves. Today it exposes the 14 tools listed below: list
your accounts and folders, search headers, read messages, download attachments and look up contacts. It can
also change a mailbox (flag, move, trash, create folders, save drafts, send), but only where the mailbox
owner switched on "Allow the AI to make changes" and ticked that permission; every mailbox is read-only by
default, and send_message only prepares an email that leaves after a human presses Send.
Try it
- Hosted: go to mcp4mail.online, sign up, connect an IMAP account, and add
https://mcp4mail.online/mcpto your MCP client. - Self-host:
cp .env.example .env, fill it in, thendocker compose up -d. See the self-hosting guide.
This project is primarily developed by AI developers orchestrated through mcptask.online. Watch the development happen live: https://mcptask.online/live
How this project is built
This is a real open-source product and, at the same time, a public demonstration. Tasks are written by
people in mcptask.online, picked up by runners (Claude Code driven by the
mcptask runner, on our own machines), and every change follows the same path: task → branch → pull request
→ tests & CI → merge → deploy to mcp4mail.online. Nobody, person or runner,
pushes to main directly: the branch is protected by a repository ruleset that requires an open pull
request, a linear history, and green status checks (security scans, lint, unit tests, system tests) before
a squash merge is allowed.
Watch it live: https://mcptask.online/live
The full story with the numbers: An open-source MCP server built by autonomous AI developers: the numbers (Dev.to, 30 October 2026).
Where to look if you want to verify any of this yourself: the Pull requests tab, where each
PR links its task and shows its CI runs, including the failed ones; CLAUDE.md and
.claude/, the instructions the runners work from; and the
CI configuration.
People still write the task briefs, review the pull requests, and decide what ships and what doesn't; a runner executes a task end to end, but it is not deciding what to build. A runner is a user with a seat here, not something free or unlimited.
MCP tools
Point your AI client at https://mcp4mail.online/mcp (or your own instance's /mcp URL) and sign in. Steps for
Claude, Claude Code, ChatGPT, Cursor and VS Code: docs/mcp-clients.md.
| Tool | What it does |
|---|---|
list_mail_accounts |
Lists the mail accounts you connected, with the ids the other tools take. |
get_mail_account |
Shows the connection details of one account (never its password). |
list_folders |
Lists the folders of one account. |
search_messages |
Searches by subject, sender, recipients, attachment names and date. |
get_message |
Reads one message. |
get_attachment |
Downloads an attachment of a message: a short-lived link, or with inline: true the file itself (up to 5 MB) inside the MCP answer. |
search_contacts |
Finds addresses you have corresponded with. |
get_outgoing_status |
Tells whether an email handed to send_message has gone out. |
set_flags |
Flags a message or marks it read / unread. Write. |
move_message |
Moves a message to another folder. Write. |
trash_message |
Moves a message to Trash. Write. |
create_folder |
Creates a folder. Write. |
create_draft |
Saves a draft. Write. |
send_message |
Prepares an email; it is sent only after you approve it. Write. |
Write tools work only on a mailbox whose owner switched on "Allow the AI to make changes to this mailbox"
and ticked what the tool does; everywhere else they are refused, see
below. send_message never sends on its own: you get an email with a
link and the message leaves only when you press Send.
Self-hosting
cp .env.example .env # fill in the values
docker compose up -d
Read docs/self-hosting.md first: which environment variables matter, why
HITCH_RESOURCE_URI must match your public URL exactly, TLS, and how mailbox passwords are stored.
Stack
Ruby 3.4, Rails 8.1, PostgreSQL, Hotwire (Turbo + Stimulus), Tailwind CSS, Solid Queue / Cache / Cable.
Development
bin/setup # install gems, prepare the database, start the dev server
bin/dev # web server + Tailwind watcher
bin/ci # rubocop, security audits, tests, system tests
PostgreSQL must be running locally; the default config connects over the local socket as your OS user.
Secrets
This repository is public. Nothing secret is ever committed: config/master.key, .env* and
credentials.yml are git-ignored, production secrets come from the environment.
Mailbox passwords are encrypted at rest with Active Record Encryption. In production, generate keys with
bin/rails db:encryption:init and provide them through the encrypted credentials
(active_record_encryption.*) or the ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY,
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY and ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT environment
variables. Development and test derive throwaway keys from the per-machine tmp/local_secret.txt.
Mail accounts
mcp4mail connects to your mailbox over plain IMAP with a username and password. Use an app-specific password wherever your provider offers one (Gmail, iCloud, Fastmail, Outlook.com, Yahoo and others do), so that what is stored in the database can be revoked on its own and is not the key to your whole account. Gmail is supported the same way: turn on two-step verification and sign in with an app password. On a Google Workspace account the administrator can switch off IMAP or app passwords, and only they can turn them back on. How the password is stored and who can decrypt it is described in the security notes of the self-hosting guide.
MCP endpoint: read-only by design
Every mailbox is read-only until you say otherwise. Each mailbox on the Mail accounts page has one switch, "Allow the AI to make changes to this mailbox", and it is off by default.
- Off (the default): the AI can only read and search. Any tool that would change the mailbox is refused
with a message telling the model the mailbox is read-only, and the refusal is written to the audit log as
denied. - On: checkboxes unfold under the switch and you tick what the AI may do in that mailbox: mark as read
and flag (
set_flags), move messages and create folders (move_message,create_folder), write drafts (create_draft), send and reply, always after your approval (send_message), delete to trash (trash_message). All are ticked when you switch it on. A tool whose box is unticked is refused the same way as on a read-only mailbox.list_mail_accountsandget_mail_accounttell the model what it may do.
The tool registry refuses to boot with a tool that is neither read-only and non-destructive nor explicitly
declared as a write tool (write_tool destructive: ..., permission: ... on McpTools::ApplicationTool,
where permission is one of the checkboxes above), so nothing can slip in as a write tool by accident.
Write tools announce readOnlyHint: false and declare their own destructiveHint.
What read-only does and does not mean, plainly:
-
Nothing can change a mailbox without its switch and the matching checkbox. Folders are opened with IMAP
EXAMINE, so even reading does not mark messages as seen. -
It does read your mail, whenever an AI client you connected asks. Connect only clients you trust with that.
-
It keeps a copy of message headers (sender, recipients, subject, date, flags, size) in its own database, refreshed every 15 minutes, so searches do not hit your mail server each time.
-
Scoping. Every tool resolves data through the signed-in user's own mail accounts; an account id that is not theirs is refused before any tool code runs.
-
Rate limits. Hitch limits each user + client pair (120 requests a minute); on top of that each user has one quota for tool calls across all their clients (240 a minute).
-
Audit log. Every call is written to
mcp_audit_events: user, client, tool, account, outcome, rows returned, duration. Arguments are not stored. -
Search guard. Pages are capped at 50 results, and each account has a budget of searches (60 per 10 minutes) and returned rows (1,000 an hour), so a runaway loop cannot walk a whole mailbox.
FAQ
Why IMAP and not the Gmail or Microsoft Graph API? The target user is on their own IMAP host, where there is no vendor API to call. Plain IMAP with a username and an app password works everywhere, so there is no Gmail or Microsoft OAuth. See Mail accounts.
Where is my mail password stored, and who can decrypt it? In PostgreSQL, encrypted with Active Record Encryption (AES-256-GCM). It is decrypted only in memory to open the IMAP connection, and never shown, returned by a tool or logged. Whoever holds the encryption keys can decrypt it; if you self-host, that is you.
Can the AI send or delete mail on its own?
No. Every mailbox is read-only until its owner switches on "Allow the AI to make changes" and ticks what is
allowed. Even then send_message only prepares an email that leaves after you press Send, and deleting
means trash_message, which moves to Trash. See
read-only by design.
Does it store my mail? Only message headers (sender, recipients, subject, date, flags, size), refreshed every 15 minutes so searches do not hit your mail server each time. Message bodies are read from your mail server when the AI asks for one.
Does it work with Outlook, Exchange or Gmail? Where the provider offers IMAP with an app password, yes: Gmail, iCloud, Fastmail, Outlook.com and Yahoo do. Whether an Exchange server allows IMAP is up to its administrator. See Mail accounts.
Is it free? Yes. It is MIT-licensed and self-hostable, and the hosted service at mcp4mail.online is run from the same code.
Contributing
See CONTRIBUTING.md. bin/ci must pass.
License
mcp4mail MCP questions
How do I add mcp4mail MCP to Claude Code?
Run claude mcp add --transport http mcp4mail https://mcp4mail.online/mcp in your terminal. Add --scope user to make it available in every project.
How do I add mcp4mail MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does mcp4mail MCP provide?
It exposes 14 tools, including list_mail_accounts, get_mail_account, list_folders, search_messages, get_message.
Can the AI send or delete mail on its own?
No. Mailboxes are read-only by default. Even with permissions enabled, sending an email requires human approval, and deleting moves messages to the Trash.
Where is my mail password stored?
Passwords are encrypted in PostgreSQL using Active Record Encryption (AES-256-GCM) and are only decrypted in memory to open the IMAP connection.
Does it store my actual emails?
It only stores message headers like sender, recipients, and subject to speed up searches; message bodies are read directly from your mail server when requested.
Does it work with Gmail or Outlook?
Yes, it works with any provider that supports IMAP and app-specific passwords, including Gmail, iCloud, Fastmail, Outlook.com, and Yahoo.