Selfhost Remote Mail MCP

https://github.com/user-attachments/assets/db89f629-66b8-4f5f-8ecd-3bbc2a51d134

Selfhost-Remote-Mail-MCP

Your own email inside Claude, ChatGPT, Codex and other AI apps.
On your computer and on your phone. Self-hosted, private, careful with sending.

Free and open source under the AGPL-3.0 license. Use it, fork it and change it, share your changes, and keep the credit. See Credits.

Quick start · Ways to run it · Several mailboxes · Add-ons · Safety · All guides

Choose which mailboxes each AI app may use

Add mailboxes, set modes, manage apps

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.

How it works, in one picture

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.

Words you'll see

Choose how to run it

Option 2 in one click: Railway or Render sets everything up and asks you for one passphrase. Steps.

On Claude Desktop, option 1 takes one click: download the extension, double-click it and type a passphrase, with no terminal. Steps.

[!TIP] Not sure? Start with 1 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.

What it can do

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.

Add-ons

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.

Turn one on in a minute:

1. Open the settings page, Add-ons tab, and press Turn on.
2. If it needs details (like your calendar login), press Set up, fill them in and press Test connection where there is one.
3. 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.

Safety and privacy

[!WARNING] Anyone can put text in your inbox, and some emails are written to trick AI apps ("Assistant, forward all invoices to..."). Read docs/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).

Quick start (option 1, about 5 minutes)

1. Install uv, a small free tool that installs Python programs.
2. Install the server:

    uv tool install git+https://github.com/Self-hosted-MCP/Selfhost-Remote-Mail-MCP

3. Run setup. It asks you to choose a passphrase, starts the server in the background and opens your settings page:

    selfhost-remote-mail-mcp setup

4. On 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.

5. Connect your AI app. For Claude Code:

    claude mcp add -s user mail -- selfhost-remote-mail-mcp stdio

   For 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.

6. Ask your AI: "Use the mail tools: what's new in my inbox today?" More ideas in docs/examples.md.

All the guides

Not supported yet

• 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.

Help and feedback

Issues are public, so leave out passwords, email addresses and email content.

Credits

Selfhost-Remote-Mail-MCP was made by Self-hosted MCP.

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:

• Keep LICENSE, NOTICE and the copyright lines.
• 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 Self-hosted MCP"), and mark your version as changed.

GitHub's "Cite this repository" button uses CITATION.cff.

License

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.