IMAP Mini MCP

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.

All tools are read-only, except for draft creation — agents can compose and update drafts but cannot send or delete emails.

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 (localhost, self-signed cert, no TLS):

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
IMAP_STARTTLS=false
IMAP_TLS_REJECT_UNAUTHORIZED=false

Tools

Listing emails

All list tools return {count, emails} where each email is {id, subject, from, date}, sorted newest-first. Optional mailbox parameter (default: "INBOX").

Addressing emails — Every email is identified by a composite id in the format YYYY-MM-DDTHH:mm:ss.<Message-ID> (e.g. 2026-02-12T14:30:25.<[email protected]>). This identifier is globally unique and stable across folder moves — unlike IMAP UIDs which are folder-scoped. Use the id returned by any list_emails_* tool 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.

list_emails_from_domain

List all emails from a specific domain.

Returns {count, emails}.

list_emails_from_sender

List all emails from a specific sender email address.

Returns {count, emails}.

fetch_email_content

Fetch the full content of a single email by id.

Returns {id, subject, from, to, date, body, attachments}. The attachments array contains metadata only: {id, filename, contentType, size}.

fetch_email_attachment

Download a specific attachment from an email.

Returns {id, filename, contentType, size, contentBase64}.

list_folders

List all folders in the email account. Takes no parameters.

Returns {count, folders} where each folder is {path, name, delimiter}. Use the path value when specifying folders in other tools.

create_folder

Create a new folder.

Returns {created} with the path of the created folder.

move_email

Move an email from one folder to another. The email is not deleted — it is atomically relocated.

Returns {id, destination}.

create_draft

Create a new email draft in the Drafts folder.

Returns {id, subject, to, date}. The Drafts folder is auto-detected via the \Drafts special-use attribute.

draft_reply

Create a reply draft to an existing email. Automatically derives recipient, subject, and threading headers from the original email.

Returns {id, subject, to, date}.

update_draft

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

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

License

MIT