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": "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 | |---|---|---|---| | IMAP_HOST | yes | — | IMAP server hostname (e.g. imap.gmail.com) | | IMAP_USER | yes | — | Email address or username | | IMAP_PASS | yes | — | Password or app-specific password | | IMAP_PORT | no | 993 | IMAP server port | | IMAP_SECURE | no | true | Use TLS for the connection | | IMAP_STARTTLS | no | true | Upgrade to TLS via STARTTLS (when IMAP_SECURE=false) | | IMAP_TLS_REJECT_UNAUTHORIZED | no | true | Reject self-signed TLS certificates |

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.<abc123@mail.example.com>). 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.

| Tool | Time range | |---|---| | list_emails_24h | Last 24 hours | | list_emails_7days | Last 7 days | | list_emails_month | Last 30 days | | list_emails_quarter | Last 90 days | | list_emails_year | Last 365 days | | list_emails_all | All time |

list_emails_from_domain

List all emails from a specific domain.

| Parameter | Type | Required | Description | |---|---|---|---| | domain | string | yes | Domain to search for (e.g. "example.com") | | mailbox | string | no | Default: "INBOX" |

Returns {count, emails}.

list_emails_from_sender

List all emails from a specific sender email address.

| Parameter | Type | Required | Description | |---|---|---|---| | sender | string | yes | Sender email address (e.g. "alice@example.com") | | mailbox | string | no | Default: "INBOX" |

Returns {count, emails}.

fetch_email_content

Fetch the full content of a single email by id.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | yes | Email identifier from list results | | mailbox | string | no | Folder hint for faster lookup |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | yes | Email identifier from list results | | attachment_id | string | yes | Attachment id from fetch_email_content | | mailbox | string | no | Folder hint for faster lookup |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | path | string | yes | Full path of the folder (e.g. "INBOX/Receipts") |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | yes | Email identifier | | source_folder | string | no | Folder hint for faster lookup | | destination_folder | string | yes | Folder to move the email to |

Returns {id, destination}.

create_draft

Create a new email draft in the Drafts folder.

| Parameter | Type | Required | Description | |---|---|---|---| | to | string | yes | Recipient email address | | subject | string | yes | Email subject line | | body | string | yes | Plain text email body | | cc | string | no | CC recipient(s) | | bcc | string | no | BCC recipient(s) | | in_reply_to | string | no | ID of email being replied to (for threading) |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | yes | ID of the email to reply to | | body | string | yes | Plain text reply body | | reply_all | boolean | no | Include original To/CC as CC (default: false) | | mailbox | string | no | Folder hint for faster lookup |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | yes | ID of the existing draft to replace | | to | string | yes | Recipient email address | | subject | string | yes | Email subject line | | body | string | yes | Plain text email body | | cc | string | no | CC recipient(s) | | bcc | string | no | BCC recipient(s) | | in_reply_to | string | no | ID of email being replied to (for threading) |

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