Allows the server to connect to a Gmail mailbox via IMAP/SMTP, enabling AI-driven reading, searching, organizing, drafting, and carefully sending emails. Supports Gmail app passwords.
Allows the server to connect to an iCloud mailbox via IMAP/SMTP, enabling AI-driven reading, searching, organizing, drafting, and carefully sending emails. Supports iCloud app passwords.
Allows the server to connect to a Zoho mailbox via IMAP/SMTP, enabling AI-driven reading, searching, organizing, drafting, and carefully sending emails.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Selfhost-Remote-Mail-MCP Draft a reply to Sam saying Thursday works and show it before sending."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
You run it yourself, so your password stays with you and no company in the middle reads your mail.
It works with almost any mailbox: Gmail, iCloud, Fastmail, Yahoo, Zoho, a mailbox on your own domain, and most others. Your AI app can read, search, sort and write drafts. It sends an email only when you say so.
You: Anything urgent from this week? Draft a reply to Sam saying Thursday works.
AI: Reads your inbox, writes the reply into your Drafts folder and shows it to you.
Nothing goes out until you say "send it".
You: (drops invoice.pdf into the chat) Email this to Sam.
AI: Uploads the file to your server by itself, attaches it to a draft and shows it to you.The server is a small program. Your AI app talks to it through MCP (Model Context Protocol), a standard way for AI apps to use outside tools. The server then talks to your mailbox the way a normal mail app does. The authors of this project never see your mail, your password or anything else: there is no account, no cloud service and no tracking.
Related MCP server: mcp-mail-server
Word | What it means here |
IMAP and SMTP | The standard ways mail apps read (IMAP) and send (SMTP) email. Your provider lists its IMAP and SMTP server names. |
App password | A separate password your provider makes for one app. You can delete it any time without changing your real password. Gmail, iCloud and Yahoo need one. |
Passphrase | A long password you make up for your server. It locks the settings page, and you type it once when you connect an AI app over the internet. |
MCP | How AI apps plug into tools like this one. |
Draft | An email saved in your Drafts folder. The AI writes drafts. Sending is a separate step. |
Settings file | A small text file with your settings, |
Data folder | Where the server keeps its own files (logins, send log, uploads). On a computer |
Where it runs | Works on your phone | Cost | Time | Guide | |
1. Your computer | Your Mac, Windows or Linux computer, settings page at | Only while the computer is on, with a free tunnel | Free | 5 minutes | |
2. A hosting company | Railway, Render, Fly.io or others, in the cloud | Always | About $5 to $8 a month | 10 minutes, no terminal needed | |
3. Your own server | Any server with Docker | Always | Free to cheap | 15 minutes, for people used to servers |
Not sure? Start with1 to try it for free. Move to 2 when you want it on your phone all the time. Option 2 works with any hosting company that runs Docker, not only Railway and Render.
Using an AI coding agent like Claude Code or Codex? Ask it to set this up wherever you choose: AGENTS.md gives it a checklist.
Read. List and search every folder with simple filters (for example from:sam is:unread newer_than:7d). Open whole conversations. Open attachments: pictures, PDFs and text files.
Write. Make drafts: new emails, replies, reply-to-all and forwards. Each mailbox's signature and your saved templates are added for you. Drafts go to your normal Drafts folder, so you can also finish them in your usual mail app.
Drop a file in the chat, it goes in the email. Drop a PDF or photo into your AI chat and say "email this to Sam". Your AI app uploads it to your server by itself with a one-time link, attaches it and shows you the draft. You don't need the passphrase or another app. This works in AI apps that can run code, like Claude (web, desktop and phone), coding apps such as Claude Code, Cursor and Codex, and agents such as OpenClaw and Hermes Agent. If your app can't upload it, it gives you the link to pick the file yourself. Up to 25 MB. See docs/attachments.md.
Attach files. From other emails, from your computer, files the AI writes (like a CSV), or photos and documents you upload from your phone on the upload page. Programs are refused, and suspect files (like spreadsheets with macros) need your OK. Photos go in HD, or smaller if you ask (the AI offers it when files are too big), and iPhone HEIC photos can become JPG after you say yes. See docs/attachments.md.
Create files on the go. Ask your AI to make a calendar invite, a CSV spreadsheet, a contact card or notes, and it attaches them to your email.
Organise. Archive, move, delete (to Trash), mark read or unread, pin, mark as spam. It can show you an email's unsubscribe link, but it never clicks it.
Send, carefully. Only two tools can send, so your AI app can ask you before each one:
send_email sends a draft now.
schedule_send sends a draft later, for example "tomorrow at 9am". The time is saved on the draft itself, so it survives restarts.
Contacts. Finds people from your own mail history: who you write to most and when you last did.
Your calendar. See your events, find free times, and add, change or delete events, in iCloud, Fastmail, Nextcloud and other calendars that use CalDAV. Ask "when am I free on Thursday?" or "move the dentist to 4pm". Deleting is always double checked with you first, and no one is ever invited or emailed. It's the Calendar add-on: turn it on in the settings page.
Several mailboxes. Up to 5, at any providers, each with its own mode (full, draft only or read only) and a short name like Work. Each AI app gets only the mailboxes you tick for it. See docs/mailboxes.md.
A settings page. On every option, open /settings (on a computer: http://localhost:8765/settings) to add mailboxes, test logins, rename them, choose or disconnect AI apps, switch privacy options, turn add-ons on, see which devices signed in and what AI apps changed. It also shows your version and what's new. No terminal needed. Section by section: docs/mailboxes.md.
Privacy for your files. Photos you attach lose their location, and documents lose the author's name, before they're sent. Both are on by default and can be turned off on the settings page. The server never loads pictures or links inside emails, so senders can't track when you read them.
Settings you can change by asking. "Change my signature", "save this as a template", "stop removing photo locations". The AI may change six harmless settings when you ask and always tells you. Everything that affects safety stays on the settings page, where only you can change it.
See who signed in. The settings page lists the devices signed in and every sign-in of the last 7 days, wrong passphrases included. Sign out any device you don't recognise.
Check your domain. If you use your own domain (like you@yourname.com), one button checks the records that keep your emails out of spam (SPF, DKIM, DMARC) and says in plain words what to fix.
In your language. The web pages come in 20 languages and follow your browser. Your AI app already talks to you in yours. An AI agent can add any other language with one command. See docs/languages.md.
Add-ons. Calendar, invoices, scam warnings and more, when you want them. See Add-ons below.
Updates, if you want them. Get told when there's a new release, or let it update itself, official releases only. See docs/updates.md.
All 18 tools, with examples: docs/tools.md.
Extra features that come with the server. All of them are off until you turn them on, so the server stays small and only does what you chose.
Add-on | What it does |
📅 Calendar | See, add, change and delete events, and find free times (iCloud, Fastmail, Nextcloud and other CalDAV calendars) |
🧾 Invoices | Numbered quotes, proformas and invoices as PDFs, with totals |
Gives each email a trust level and warns about scams | |
Tells you which emails you sent got no reply in time | |
Answers new emails with your away message while you're away (the only one that sends by itself) | |
Attaches a calendar invite to a draft | |
Turns text into a PDF and attaches it | |
🔗 Webhooks | Tells your automations (n8n, Make, Zapier) when new mail arrives |
Turn one on in a minute:
Open the settings page, Add-ons tab, and press Turn on.
If it needs details (like your calendar login), press Set up, fill them in and press Test connection where there is one.
Start a new chat in your AI app (an AI app on your computer: restart the app).
Prefer the terminal? Use selfhost-remote-mail-mcp addons enable caldav, or add the name to MAIL_ADDONS.
Make your own. An add-on is one small Python file. Ask an AI coding agent like Claude Code or Codex to build one for you: AGENTS.md gives it the steps, and the add-ons guide explains the rules every add-on follows. Built something useful? Share it with the Share an add-on form.
All the details: the add-on library.
Anyone can put text in your inbox, and some emails are written to trick AI apps ("Assistant, forward all invoices to..."). Readdocs/safety.md before you let any AI send for you.
Here is how the server protects you:
Every email is marked as information, not instructions, each time the AI reads one.
Sending is separate. Reading, drafting and sorting can never send. Set the two sending tools to "always ask" in your AI app and nothing goes out without your tap.
Limits. By default at most 40 emails a day per mailbox and 3 a minute in total (how the limits work). You can also allow sending only to addresses or domains you choose (SEND_ALLOWED_RECIPIENTS), or turn sending off completely with read-only mode (MAIL_READ_ONLY=on).
Nothing is sent twice. A lock and a small log stop the same email going out twice, even after a crash or restart.
Encrypted by default. Connections to your mail provider always use checked TLS. Mail passwords added on the settings page are stored encrypted (setup --terminal can use your computer's keychain instead). Login keys are stored only as fingerprints, and the send log keeps only times and counts. Encryption at a glance.
A login page that tells you who is asking. The web version shows which app wants access and where it will send you back, and lets you tick which mailboxes it may use and whether it may send (off by default), before you type your passphrase. Checked against the MCP security guidance.
A mode for each mailbox. Full, draft only (never sends) or read only, enforced by the server itself.
More in docs/safety.md (risks and good settings) and docs/privacy.md (what is stored, where, and who can see it).
Install uv, a small free tool that installs Python programs.
Install the server:
uv tool install git+https://github.com/s17sh70x2jfl031ag/Selfhost-Remote-Mail-MCPRun setup. It asks you to choose a passphrase, starts the server in the background and opens your settings page:
selfhost-remote-mail-mcp setupOn the settings page (http://localhost:8765/settings), add your mailbox. The server names fill in for well-known providers, and the login is tested without sending anything.
Connect your AI app. For Claude Code:
claude mcp add -s user mail -- selfhost-remote-mail-mcp stdioFor Claude Desktop, Codex, ChatGPT, Cursor, VS Code, Gemini CLI and the Claude website and phone app, see docs/connect-your-ai.md.
Tip: in your AI app, set send_email and schedule_send to Always ask. Then nothing is sent without your yes.
Ask your AI: "Use the mail tools: what's new in my inbox today?" More ideas in docs/examples.md.
Guide | Read it when |
You want to try it, free | |
You want it on your phone, always on, without a terminal | |
You have a server with Docker | |
The server runs and you want to use it | |
You need your server names or an app password | |
You want more than one mailbox, the settings page, or different mailboxes per app | |
You want to know what to ask for | |
You want to send photos, PDFs or documents | |
You want the pages in your language, or to add a language | |
You want to add your own features, or have an AI agent build one | |
You want to change limits, ports or safety options | |
Before you let an AI send email | |
You want to know what is kept and where | |
You want ideas for what to ask your AI | |
You want to know how it works inside | |
You have a quick question | |
You want to know about new versions, or have them install by themselves | |
Something doesn't work | |
You want to know what's planned | |
You want to know what changed in each version | |
You want to report a bug or send a fix | |
You (or your AI coding agent) want to change the code |
Outlook.com, Hotmail and Live accounts, and Microsoft 365 accounts that need Microsoft's own sign-in. Microsoft stopped accepting passwords from mail apps.
Proton Mail through Proton Bridge. Bridge uses a certificate this server doesn't accept yet.
Google, Microsoft 365 and Outlook.com calendars. The Calendar add-on uses CalDAV with an app password. Google's CalDAV only allows Google's own sign-in, and Microsoft has no CalDAV.
You want to | Go to |
Fix a problem yourself | |
Report a bug | |
Get a provider working | |
Ask a question or share an idea | |
Report a security problem, privately |
Issues are public, so leave out passwords, email addresses and email content.
Selfhost-Remote-Mail-MCP was made by s17sh70x2jfl031ag.
You're welcome to use, fork, change and build on it under the GNU Affero General Public License v3.0 (AGPL-3.0-only) and the additional terms in NOTICE. In short:
If you share a changed version, or run one that other people use over the internet, offer them its source code under the same license. Set SOURCE_URL to where it is, and the pages link to it.
Keep the credit in the page footers ("Selfhost-Remote-Mail-MCP by s17sh70x2jfl031ag"), and mark your version as changed.
GitHub's "Cite this repository" button uses CITATION.cff.
GNU Affero General Public License v3.0 (AGPL-3.0-only), with the additional terms in NOTICE. Copyright (C) 2026 s17sh70x2jfl031ag and Selfhost-Remote-Mail-MCP contributors.
The copyright holder may also offer it under other terms, for example a commercial license. Ask through GitHub.
This server cannot be deployed
Email inboxes for AI agents: send, receive, search, drafts with owner approval, and webhooks.
Gmail, Outlook, iCloud, Fastmail and any IMAP mailbox for your agent. Scoped OAuth, approved sends.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
