Simple IMAP MCP Server

A Node.js IMAP/SMTP MCP server that provides email operations via the Model Context Protocol.

Quick Start

# Install and run locally
npm install @adam-gfam/imap-server

# OR run without installing
npx -y @adam-gfam/imap-server

Configuration

Copy .env.example to .env and fill in your IMAP/SMTP credentials. See the full Configuration Guide for details.

Usage

Once the server is running, it exposes the following tools, resources, and prompts via the MCP protocol.

Transport Modes

| Mode | Use Case | Configuration | |------|----------|---------------| | stdio | Claude Desktop, CLI tools, local agents | Default, no config needed | | Streamable HTTP | Remote LLM clients, web dashboards | MCP_TRANSPORT=http, HTTP_PORT=3000 |

IMAP Tools

• list_folders — List all IMAP mailboxes/folders. Parameters: folder_pattern, include_subfolders.
• search_emails — Search emails by criteria (folder, from, to, subject, date, keyword, unread_only). Paginated results.
• fetch_email — Fetch full email content including headers, body, and attachments by UID.
• get_email_body — Fast body-only fetch (text and/or HTML) for a given UID.
• get_email_headers — Minimal-bandwidth header fetch without downloading the body.
• mark_as_read — Toggle read/unread status via IMAP FLAGS.
• move_email — Move an email to a different IMAP folder (creates destination if needed).
• delete_email — Delete an email (moves to Trash).
• create_folder — Create a new IMAP mailbox folder (supports hierarchy like "Work/Projects").
• list_unread — Quick listing of unread messages with pagination.

SMTP Tools

• send_email — Send an email with text or HTML body. Supports to, subject, body, html, from, cc, bcc.
• send_email_with_attachment — Send an email with file attachments ([{ name, content (base64), content_type }]).
• list_drafts — List draft emails in the Drafts folder.
• save_as_draft — Save an email as a draft (plain text or HTML).
• delete_draft — Delete a draft email by UID.

MCP Resources

| Resource | Description | URI Template | |----------|-------------|-------------| | email_body | Parsed email body text | email://<folder>/<uid>/body | | email_headers | Email headers | email://<folder>/<uid>/headers |

MCP Prompts

| Prompt | Description | Arguments | |--------|-------------|-----------| | search_emails | "Help me search my emails" | query, date_range, folder | | compose_reply | "Draft a reply to this email" | email_uid, tone | | organize_inbox | "Help me organize my inbox" | criteria, folder |

Documentation

All project documentation is hosted in the Simple IMAP MCP Project collective:

• Project Overview — Architecture, tech stack, project structure
• API Reference — Complete tool and resource API docs
• Source Code Index — Source file inventory
• Configuration Guide — Env vars, installation, setup

Contributing

All future design and technical documents must be created directly in the Nextcloud collective, not locally. The collective is the single source of truth for all project documentation.

Tech Stack

• MCP Server: @modelcontextprotocol/server v2
• IMAP: imapflow v1.7
• SMTP: nodemailer v9
• MIME Parser: mailparser v3.9
• Schema: zod v4
• Env: dotenv v17