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.
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": "[email protected]",
"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
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=false
Or 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": "[email protected]",
"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.
Examples:
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.
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:
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 build
Local 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 start
When 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 only