IMAP Mini MCP
Summary: A read-and-organize IMAP server that lets an agent browse, search, fetch, move, star, and draft emails — but never send or delete them.
List emails by timeframe — last 24h, 7 days, 30 days, 90 days, 365 days, or all (per mailbox, default INBOX), sorted newest-first with
{id, subject, from, date}.Search by sender or domain —
list_emails_from_senderandlist_emails_from_domain.Fetch full content —
fetch_email_contentby globally unique id (returns subject, from/to, date, body, attachment metadata).Download attachments —
fetch_email_attachmentreturns base64-encoded file data.Manage folders —
list_foldersandcreate_folder.Organize mail —
move_emailbetween folders.Star/unstar —
star_email,unstar_email, andlist_starred_emailsacross all folders.Compose drafts —
create_draft(new draft, optional threading viain_reply_to),draft_reply(auto-derives recipient,Re:subject, and threading; optionalreply_all), andupdate_draft(replace an existing Drafts-folder draft).Safety limits — no send, no delete, and no label or bulk-move tools are exposed despite the README mentioning them.
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., "@IMAP Mini MCP Summarize the emails I received in the last 24 hours"
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.
IMAP Mini MCP
A lightweight MCP (Model Context Protocol) server for reading IMAP email and creating draft replies. Works with any standard IMAP server (Gmail, Outlook, Fastmail, etc.) and local bridges like ProtonMail Bridge.
Agents can read, search, move, star, and organize emails, and compose drafts — but cannot send or delete emails.
See CHANGELOG.md for recently added features.
Workflow Recommendation
I highly recommend using a speech-to-text tool (e.g. SuperWhisper on Mac or Whisperflow on Windows) and connecting your AI desktop application (Claude, Codex, etc.) to this MCP server. That way you can converse with your email inbox using speech, which will dramatically speed up your workflow.
Related MCP server: mail-mcp
How to Use
Agent configuration
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"imap-mini-mcp": {
"command": "node",
"args": ["/path/to/imap-mini-mcp/dist/index.js"],
"env": {
"IMAP_HOST": "imap.example.com",
"IMAP_USER": "you@example.com",
"IMAP_PASS": "your-password"
}
}
}
}The args path must point to the built dist/index.js. Add any optional variables to the env block as needed.
Environment variables
Variable | Required | Default | Description |
| yes | — | IMAP server hostname (e.g. |
| yes | — | Email address or username |
| yes | — | Password or app-specific password |
| no |
| IMAP server port |
| no |
| Use TLS for the connection |
| no |
| Upgrade to TLS via STARTTLS (when |
| no |
| Reject self-signed TLS certificates |
For most providers (Gmail, Outlook, Fastmail), the defaults work — just set host, user, and password.
For ProtonMail Bridge — all five settings below are required (the bridge listens on localhost without TLS, uses a self-signed certificate, and does not support STARTTLS):
IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
IMAP_STARTTLS=false
IMAP_TLS_REJECT_UNAUTHORIZED=falseOr as MCP client config:
{
"mcpServers": {
"imap-mini-mcp": {
"command": "node",
"args": ["/path/to/imap-mini-mcp/dist/index.js"],
"env": {
"IMAP_HOST": "127.0.0.1",
"IMAP_PORT": "1143",
"IMAP_SECURE": "false",
"IMAP_STARTTLS": "false",
"IMAP_TLS_REJECT_UNAUTHORIZED": "false",
"IMAP_USER": "you@proton.me",
"IMAP_PASS": "your-bridge-password"
}
}
}
}Tools
Every email is identified by a composite id (YYYY-MM-DDTHH:mm:ss.<Message-ID>) that is globally unique and stable across folder moves. Use the id returned by find_emails to fetch content, download attachments, move emails, or create reply drafts. Action tools accept an optional mailbox hint for faster lookup; if omitted, all folders are searched.
find_emails
Search and filter emails. All parameters are optional — calling with no parameters returns all emails from INBOX, sorted newest-first.
Parameter | Type | Default | Description |
| string | — | Only emails after this time. Relative ( |
| string | — | Only emails before this time. Same formats as |
| string | — | Substring match on sender address (e.g. |
| string | — | Substring match on subject line |
| boolean |
| Only return unread emails |
| boolean |
| Only return emails with attachments |
| string |
| Folder to search |
| number | — | Maximum number of results (newest first) |
Examples:
Use case | Parameters |
Last 24 hours |
|
Last 7 days, max 10 |
|
Unread emails |
|
From a domain |
|
With attachments, last month |
|
Specific sender, in Sent folder |
|
Other tools
Labels are tags that appear alongside emails (not folders). They are implemented as IMAP folders under the Labels/ namespace — add_label copies the email to Labels/<name>, remove_label deletes that copy, and the original email stays in its source folder. This is natively supported by Proton Mail and compatible with any IMAP server that exposes labels as folders.
Tool | Description | Key parameters |
| Starred emails across all folders (includes Apple Mail color flags) | — |
| Emails with an Apple Mail color flag, grouped by folder |
|
| Full email content by id |
|
| Download an attachment |
|
| List all folders | — |
| Create a new folder |
|
| Move an email to another folder |
|
| Move all emails from a sender |
|
| Move all emails from a domain |
|
| Add a label (tag) to an email |
|
| Remove a label from an email |
|
| List all labels | — |
| Star an email |
|
| Unstar an email |
|
| Mark an email as read |
|
| Mark an email as unread |
|
| Create a new draft |
|
| Create a reply draft from an existing email |
|
| Replace an existing draft (Drafts folder only) |
|
Troubleshooting
"IMAP connection closed unexpectedly" or "Server disconnected"
This almost always means the server rejected the connection due to a TLS/STARTTLS mismatch. Verify these environment variables are set correctly in your MCP client config:
Variable | Check |
| Correct hostname or IP |
| Matches your server (993 for TLS, 143/1143 for plain) |
|
|
|
|
|
|
Local IMAP bridges (e.g. ProtonMail Bridge) typically require IMAP_SECURE=false, IMAP_STARTTLS=false, and IMAP_TLS_REJECT_UNAUTHORIZED=false. See the ProtonMail Bridge config example in the Environment variables section above.
"IMAP authentication failed"
Check that IMAP_USER and IMAP_PASS are correct. Some providers (e.g. Gmail) require an app-specific password rather than your account password.
"Cannot reach IMAP server — connection refused"
The IMAP server is not running or not listening on the configured host and port. For local bridges, make sure the bridge application is running.
Development
Build and run
npm install
npm run buildLocal development with .env
For running the server directly (outside of an MCP client), copy .env.example to .env and fill in your credentials, then:
npm startWhen used through an MCP client, credentials are provided via the client config's env block instead.
Testing
Tests use vitest and mock the IMAP layer — no real server connection is needed:
npm test # run once
npm run test:watch # watch mode
npm run lint # type-check onlyLicense
Available Tools
19 toolscreate_draftA
Create a new email draft in the Drafts folder. Returns {id, subject, to, date} of the created draft. Optionally set in_reply_to with an email id to create a threaded reply draft (sets In-Reply-To and References headers automatically).
Inputs: to (required), subject (required), body (required), cc, +2 more.
create_folderA
Create a new folder. Use a path with the server's delimiter for subfolders (e.g. "INBOX/Receipts" or "Projects/2024"). Use list_folders first to discover the delimiter if unsure.
Inputs: path (required).
draft_replyA
Create a reply draft to an existing email. Automatically derives recipient, subject (Re: prefix), and threading headers from the original email. Set reply_all to true to include original recipients as CC. Returns {id, subject, to, date} of the created draft.
Inputs: id (required), body (required), reply_all, mailbox.
fetch_email_attachmentA
Download a specific attachment from an email. Requires the email id and the attachment id (obtained from fetch_email_content). Returns {id, filename, contentType, size, contentBase64} where contentBase64 is the base64-encoded file content.
Inputs: id (required), attachment_id (required), mailbox.
fetch_email_contentA
Fetch the full content of a single email by its id. Returns {id, subject, from, to, date, body, attachments}. The attachments array contains metadata only (id, filename, contentType, size) — use fetch_email_attachment to download actual attachment data. Use an id obtained from any of the list_emails_* tools.
Inputs: id (required), mailbox.
list_emails_24hA
List all emails received in the last 24 hours. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: mailbox.
list_emails_7daysA
List all emails received in the last 7 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: mailbox.
list_emails_allA
List ALL emails in the mailbox (no date filter). Warning: this may return a very large number of results. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: mailbox.
list_emails_from_domainA
List all emails from a specific domain (e.g. "you.com" finds all emails from @you.com senders). Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: domain (required), mailbox.
list_emails_from_senderA
List all emails from a specific sender email address (e.g. "alice@example.com"). Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: sender (required), mailbox.
list_emails_monthA
List all emails received in the last 30 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: mailbox.
list_emails_quarterA
List all emails received in the last 90 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: mailbox.
list_emails_yearA
List all emails received in the last 365 days. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: mailbox.
list_foldersA
List all folders in the email account. Returns an array of {path, name, delimiter} objects. Use the path value when specifying a folder in other tools.
Inputs: no named parameters.
list_starred_emailsA
List all starred (flagged) emails across all folders, grouped by folder. Returns an array of {id, subject, from, date} objects sorted newest-first. The id is a globally unique identifier — use it with fetch_email_content to read the full email.
Inputs: no named parameters.
move_emailA
Move an email from one folder to another. Requires the email's id (from list_emails_* or fetch_email_content) and the destination folder to move it to. Returns {id, destination}.
Inputs: id (required), destination_folder (required), source_folder.
star_emailA
Add a star (flag) to an email. Requires the email's id (from list_emails_* or fetch_email_content). Returns {id, starred: true}.
Inputs: id (required), mailbox.
unstar_emailA
Remove the star (flag) from an email. Requires the email's id (from list_emails_* or fetch_email_content). Returns {id, starred: false}.
Inputs: id (required), mailbox.
update_draftA
Replace an existing draft with new content. The id must refer to an email in the Drafts folder — this tool cannot modify emails in other folders. Returns {id, subject, to, date} of the updated draft.
Inputs: id (required), to (required), subject (required), body (required), +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have distinct purposes, but the multiple list_emails_* tools (e.g., list_emails_24h, list_emails_7days) serve overlapping functions with only time filters differing, which could cause confusion in selection. However, descriptions clarify their specific scopes, and other tools like create_draft, move_email, and star_email are clearly differentiated.
All tool names follow a consistent verb_noun pattern with snake_case, such as create_draft, list_folders, and fetch_email_content. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming conventions.
With 19 tools, the count is borderline high for an email management server, as many list_emails_* tools could be consolidated into a single tool with parameters. While it covers various use cases, the number feels heavy and may overwhelm agents, though it's not extreme.
The tool set provides comprehensive coverage for email operations, including CRUD for drafts, folder management, email listing with filters, attachment handling, and actions like starring and moving. Minor gaps include no direct send_email tool (relying on drafts) and limited search beyond sender/domain, but core workflows are well-supported.
Maintenance
Related MCP Connectors
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Your mailbox for MCP clients: search, read, draft, send, rules and notes. Sending is off by default.
Your own IMAP mailbox in any MCP client: search, read, flag, move; send and delete need confirm.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that enables AI models to read, search, and send emails via IMAP and SMTP protocols. It supports various providers like Gmail and Outlook, allowing for tasks such as retrieving unread messages, searching by sender, and managing mailbox folders.-
- AlicenseNot gradedqualityDmaintenanceA generic IMAP and SMTP MCP server that enables AI agents to interact with email accounts for reading, searching, and sending messages. It provides high-level tools for managing email workflows like daily digests and folder organization across any standard email provider.1MIT
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server for IMAP email access, enabling AI agents to read, search, and monitor email without sending or deleting messages.MIT
- AlicenseNot gradedqualityDmaintenanceA minimal MCP server for reading, searching, managing, and sending email over IMAP and SMTP.MIT