Skip to main content
Glama

IMAP Mini MCP

Made with AI Verified by Humans

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

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 — 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": "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

after

string

—

Only emails after this time. Relative ("30m", "2h", "7d") or ISO date ("2026-02-20")

before

string

—

Only emails before this time. Same formats as after

from

string

—

Substring match on sender address (e.g. "alice@example.com", "@stripe.com")

subject

string

—

Substring match on subject line

unread_only

boolean

false

Only return unread emails

has_attachment

boolean

false

Only return emails with attachments

folder

string

"INBOX"

Folder to search

limit

number

—

Maximum number of results (newest first)

Examples:

Use case

Parameters

Last 24 hours

{after: "24h"}

Last 7 days, max 10

{after: "7d", limit: 10}

Unread emails

{unread_only: true}

From a domain

{from: "@stripe.com"}

With attachments, last month

{after: "30d", has_attachment: true}

Specific sender, in Sent folder

{from: "alice@example.com", folder: "Sent"}

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

list_starred_emails

Starred emails across all folders (includes Apple Mail color flags)

—

list_emails_by_color

Emails with an Apple Mail color flag, grouped by folder

color? (red/orange/yellow/green/blue/purple/grey)

fetch_email_content

Full email content by id

id, mailbox?

fetch_email_attachment

Download an attachment

id, attachment_id, mailbox?

list_folders

List all folders

—

create_folder

Create a new folder

path

move_email

Move an email to another folder

id, destination_folder, source_folder?

bulk_move_by_sender_email

Move all emails from a sender

sender, source_folder, destination_folder

bulk_move_by_sender_domain

Move all emails from a domain

domain, source_folder, destination_folder

add_label

Add a label (tag) to an email

id, label, source_folder?

remove_label

Remove a label from an email

id, label

list_labels

List all labels

—

star_email

Star an email

id, mailbox?

unstar_email

Unstar an email

id, mailbox?

mark_read

Mark an email as read

id, mailbox?

mark_unread

Mark an email as unread

id, mailbox?

create_draft

Create a new draft

to, subject, body, cc?, bcc?, in_reply_to?

draft_reply

Create a reply draft from an existing email

id, body, reply_all?, mailbox?

update_draft

Replace an existing draft (Drafts folder only)

id, to, subject, body, cc?, bcc?, in_reply_to?

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

IMAP_HOST

Correct hostname or IP

IMAP_PORT

Matches your server (993 for TLS, 143/1143 for plain)

IMAP_SECURE

true for port 993, false for plain connections

IMAP_STARTTLS

false if your server does not support STARTTLS

IMAP_TLS_REJECT_UNAUTHORIZED

false if your server uses a self-signed certificate

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

License

MIT

Available Tools

19 tools
create_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

    A4.1/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      An 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server for IMAP email access, enabling AI agents to read, search, and monitor email without sending or deleting messages.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A minimal MCP server for reading, searching, managing, and sending email over IMAP and SMTP.
      MIT