SkillFoxx

imap-mcp-server: email over IMAP and SMTP for agents

imap-mcp-server

An MCP server for searching, reading, sending and cleaning up email in several mailboxes, with credentials stored under AES-256

  • 129 ★ on the repository
  • Last commit
  • MIT
MCP server

Broad access

Why this level

  • The agent reads the whole mailbox, sends email in your name and can delete messages in bulk
  • Mailbox logins and passwords sit in a file on disk with the encryption key next to it: protect those files
All reasons and checks

nikolausm/imap-mcp-serverAuthor:nikolausm

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/imap-mcp-server

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Broad accessThe tool can change data, run commands or handle secrets.

  • The agent reads the whole mailbox, sends email in your name and can delete messages in bulk
  • Mailbox logins and passwords sit in a file on disk with the encryption key next to it: protect those files

This is third-party code. Review the repository files before installing.

What it does

imap-mcp-server connects an agent to mailboxes over IMAP and SMTP. The agent searches mail, reads it, moves it between folders, sets flags and labels, downloads attachments, writes drafts, sends, replies and forwards. There are tools for listing folders, unread counts, finding a thread by Message-ID and domain statistics. Accounts are stored in `~/.imap-mcp/accounts.json`, passwords are encrypted with AES-256-CBC, and the key lives separately in `~/.imap-mcp/.key`. The files are readable only by the owner. A web wizard adds mailboxes: it listens on `127.0.0.1` only and knows the settings of more than 15 providers, including Gmail, Outlook and Yahoo. SMTP settings are derived from the IMAP provider. The server keeps a connection pool and works with several mailboxes at once. There is deletion by search, by domain and spam cleanup: these tools are dangerous, so they can be hidden. The `IMAP_MCP_READ_ONLY` variable leaves only search, reading and counts.

Who it is for. People who want an agent in Claude Desktop, Claude Code or Cursor to sort, search and send email, including several mailboxes at different providers.

Good fit when

  • You need every email from a supplier over the quarter found in a work mailbox and summed up in a list
  • Mail needs sorting: newsletters moved to a folder and marked as read
  • The agent drafts a reply and you decide whether to send it
  • You want to clean spam and mail from one domain out of a mailbox after checking the list
  • There are several mailboxes and one assistant should cover all of them with shared search

Not a fit when

  • A one-off export of mail is enough: a mail client export is simpler than standing access for an agent
  • The agent cannot be trusted to send and delete without review: enable `IMAP_MCP_READ_ONLY` or skip the server
  • You need OAuth sign-in for Gmail or Outlook: the server uses a login and password, often an app password

Example request

Find emails from accounting for October, make a list with subjects and dates and prepare a draft reply to the latest one without sending it.

MCP

Transport
stdio
Authentication
key is optional

Environment variables

IMAP_MCP_READ_ONLY
Set to 1 to keep read-only tools only.
IMAP_MCP_WIZARD_TOKEN secret
Web wizard token when it is not bound to loopback, at least 16 characters.

Limitations

It needs Node 22.12 or newer: versions 18 and 20 are end of life and the package dependencies no longer support them. Access uses a login and password, and many providers require an app password for that.

By default the agent sees every tool, including sending and bulk deletion. Read-only mode is switched on with `IMAP_MCP_READ_ONLY`, and a hand-picked tool set is set with a separate variable. If the IMAP server lacks search support, a slow fallback downloads every envelope of the folder, and body search is refused above 2000 candidates.

The delete-by-search, delete-by-domain and spam cleanup tools return an error on that fallback path: find messages with `imap_search_emails` and delete their UIDs instead.

How to disable. Remove the server from the MCP client configuration. Delete stored accounts by hand: the `~/.imap-mcp` folder holds the encrypted `accounts.json` and the `.key` file.

FAQ

How do I install it?

The easiest way is `npx -y imap-mcp-server`, which needs Node 22.12 or newer. There are also `install.sh` and `install.ps1` scripts, but do not run them blindly: read them first.

Where are passwords stored?

In `~/.imap-mcp/accounts.json`, encrypted with AES-256-CBC, with the key stored separately in `~/.imap-mcp/.key`. The folder and files are owner-only.

Can I give the agent read-only access?

Yes. The `IMAP_MCP_READ_ONLY` variable set to `1` keeps search, reading, folder lists, unread counts and spam analysis. Sending, moving and deleting are not registered.

How do I add a mailbox?

Run the web wizard with `npx -p imap-mcp-server imap-setup`: it opens a browser with provider presets. Or ask the assistant to call `imap_add_account`, though the password then passes through the chat.

Can I keep passwords outside the file?

Yes, the username and password of an existing account can be overridden by environment variables like `IMAP_MCP_ACCOUNT_<NAME>_IMAP_PASSWORD`. The value goes into an encrypted in-memory cache and is removed from `process.env`.

Discussion

No questions or reviews yet.

MCP servers

MCP email server over IMAP and SMTP: an agent searches, reads, sorts and sends mail across several mailboxes

MCP serverBroad access393

An email MCP with 52 tools: the agent reads, searches, sends and sorts mail across several accounts over IMAP and SMTP, and schedules sends

MCP serverBroad access158

An MCP server for Mail on Mac: an agent reads, searches, writes and sorts email and triages the inbox, with a read-only mode

MCP serverBroad access256

MCP server for Apple Mail on macOS: read, search, send and organize mail through AppleScript or IMAP and SMTP.

MCP serverBroad access111
Russian stack

A small read-only MCP server for Mail.ru mail: listing, reading, searching and folders, with no ability to send or delete

MCP serverBroad access

README in short

The README lists features, installation through npx and scripts, account setup with the web wizard and credential overrides through the environment. It then covers client configs, tool restriction, a description of every tool with parameters and a security section.

README badge

Report a problem