mcp4mail

Name: mcp4mail
Author: jchsoft

by jchsoftversion 1.0.0i★ –iRuns in the cloud

Registry nameonline.mcp4mail/mcp4mail

Install

Overview

Description from the maker (original English)

Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi3 of 3 passedChecked from public information; code not scanned yet
UsageiVery new★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs in the cloud
Transport: Streamable HTTP
Category: Search & AI memory

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 3 of 3 passed
Runs on the maker’s server: what you ask it goes through their server.
The registry lists no key to fill in.

You need

Runs in the cloudNothing to install; it connects over the internet

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Works in Claude on the web, desktop and mobile:

Open Settings → Connectors
Press Add custom connector
Paste the address below and press Add
If it asks you to sign in, sign in with the maker

https://mcp4mail.online/mcp

Run this in your terminal

claude mcp add --transport http mcp4mail https://mcp4mail.online/mcp

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp4mail": {
      "url": "https://mcp4mail.online/mcp"
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "mcp4mail": {
      "type": "http",
      "url": "https://mcp4mail.online/mcp"
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

ChatGPT connects only to servers on the internet:

Open ChatGPT on the web → Settings → Connectors (Apps)
Press Create or Add (some plans need Developer mode under Advanced first)
Paste the address below, give it a name and save
If it asks you to sign in, sign in with the maker

https://mcp4mail.online/mcp

Menu names can differ slightly by plan and over time.

Your choice stays on this device in a cookie; no account needed.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

The server asks you to sign in before it lists its tools.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 9, 2026

✓ Pass
Maker matches the repo
The registry name was verified against the domain mcp4mail.online (the registry checks domain ownership)
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
✓ Pass
Endpoint responds
Responded in 741 ms (HTTP 401)
✓ Pass
Sign-in with OAuth
Declares OAuth sign-in, so your AI app can take you to log in
… Not checked yet
No hidden instructions in tool descriptions
Not checked yet; we read the tool list when we check the endpoint

Compared with others in Search & AI memoryi

More stars than 0% of the other 5756 servers in this category
Published to the registry more recently than 49% of the other 5756 servers in this category
Basic checks equal to or better than 100% of the other 5756 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is mcp4mail safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs in the maker’s cloud. Connect over the internet with nothing to install, but what you send passes through the maker’s servers.

Is it still maintained?

The GitHub repo last changed –, and the latest version (1.0.0) reached the registry 42 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. It connects by URL, so apps that accept remote MCP servers work too, such as ChatGPT in developer mode.

What can I use instead?

In the same category: Context7, Codebase Memory, Exa

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Context7

Feeds AI the latest docs for libraries and frameworks before it answers, so code it writes does not use outdated, removed functions.

by upstashWidely used↓ 972.7K/wk★ 64.2KUpdated 3 days ago

Computer or cloud

Install

Codebase Memory

Codebase knowledge graph for AI agents — 162 languages, sub-ms queries, 99% fewer tokens.

by DeusDataWidely used↓ 18K/wk★ 48.1KUpdated 23 days ago

Runs on your computer

Install

Exa

Connect AI agents to Exa for web search, content fetching, and multi-step research.

by exa-labsWidely used★ 5.2KUpdated 2 months ago

Runs in the cloud✓ exa.ai

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

mcp4mail

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/mcp to your MCP client.
Self-host: cp .env.example .env, fill it in, then docker 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

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_accounts and get_mail_account tell 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

MIT

mcp4mail

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Search & AI memoryi

Common questions

Alternatives

Context7

Codebase Memory

Exa

README from the maker

mcp4mail

Try it

How this project is built

MCP tools

Self-hosting

Stack

Development

Secrets

Mail accounts

MCP endpoint: read-only by design

FAQ

Contributing

License