Skip to content
Back to search

imap-mcp-server

A powerful Model Context Protocol (MCP) server for IMAP email integration with Claude

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nikolausm/imap-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nikolausm/imap-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nikolausm--imap-mcp-server/badge.svg)](/listings/nikolausm--imap-mcp-server)

HTML

<a href="/listings/nikolausm--imap-mcp-server"><img src="/api/listings/nikolausm--imap-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

> **Requires Node.js 22.12 or newer.** Node 18 and 20 have both reached > end-of-life, and several of this package's dependencies no longer support > them. Check yours with `node --version`.

Run via npx (No Installation Required)

Once published to npm, you can run the server directly without cloning or building anything — `npx` downloads the prebuilt package and runs it:

npx -y imap-mcp-server

This is the easiest way to use the server in an MCP client (see [Configuration](#configuration) for ready-to-paste `npx` configs).

Quick Install (Recommended)

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.sh | bash

Windows (PowerShell as Administrator):

iwr -useb https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.ps1 | iex

Manual Installation

1. Clone the repository:

git clone https://github.com/nikolausm/imap-mcp-server.git
cd imap-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 861 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # IMAP MCP Server
  2. [![MCPVault: claimed](https://mcpvault.io/badge/imap-mcp-server.svg)](https://mcpvault.io/servers/imap-mcp-server/health?utm_source=external_badge&utm_medium=referral&utm_campaign=mcp_health_report)
  3. A powerful Model Context Protocol (MCP) server that provides seamless IMAP email integration with secure account management and connection pooling.
  4. ## Features
  5. - 🔐 **Secure Account Management**: Encrypted credential storage with AES-256 encryption
  6. - 🚀 **Connection Pooling**: Efficient IMAP connection management
  7. - 📧 **Comprehensive Email Operations**: Search, read, move, mark, delete, and bulk delete emails
  8. - ✉️ **Email Sending**: Send, reply, and forward emails via SMTP
  9. - 📁 **Folder Management**: List folders, check status, get unread counts
  10. - 🔄 **Multiple Account Support**: Manage multiple IMAP accounts simultaneously
  11. - 🛡️ **Type-Safe**: Built with TypeScript for reliability
  12. - 🌐 **Web-Based Setup Wizard**: Easy account configuration with provider presets
  13. - 📱 **15+ Email Providers**: Pre-configured settings for Gmail, Outlook, Yahoo, and more
  14. - 🔗 **Auto SMTP Configuration**: Automatic SMTP settings based on IMAP provider
  15. ## Installation
  16. > **Requires Node.js 22.12 or newer.** Node 18 and 20 have both reached
  17. > end-of-life, and several of this package's dependencies no longer support
  18. > them. Check yours with `node --version`.
  19. ### Run via npx (No Installation Required)
  20. Once published to npm, you can run the server directly without cloning or building anything — `npx` downloads the prebuilt package and runs it:
  21. ```bash
  22. npx -y imap-mcp-server
  23. ```
  24. This is the easiest way to use the server in an MCP client (see [Configuration](#configuration) for ready-to-paste `npx` configs).
  25. ### Quick Install (Recommended)
  26. #### macOS/Linux:
  27. ```bash
  28. curl -fsSL https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.sh | bash
  29. ```
  30. #### Windows (PowerShell as Administrator):
  31. ```powershell
  32. iwr -useb https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.ps1 | iex
  33. ```
  34. ### Manual Installation
  35. 1. Clone the repository:
  36. ```bash
  37. git clone https://github.com/nikolausm/imap-mcp-server.git
  38. cd imap-mcp-server
  39. ```
  40. 2. Install dependencies:
  41. ```bash
  42. npm install
  43. ```
  44. 3. Build the project:
  45. ```bash
  46. npm run build
  47. ```
  48. ## Account Setup
  49. Accounts are stored encrypted in `~/.imap-mcp/accounts.json`. This file is **shared by all run modes** — whether you start the server via `npx`, a global install, or a local clone, they all read the same accounts. So you only need to set up your accounts once.
  50. ### Setting Up Accounts in npx Mode
  51. If you run the server via `npx` (no clone), you have two ways to add accounts:
  52. **Option A — Run the setup wizard directly via npx (no install needed):**
  53. ```bash
  54. npx -p imap-mcp-server imap-setup
  55. ```
  56. This launches the same web-based wizard described below and writes to `~/.imap-mcp/accounts.json`, which your `npx`-configured MCP server then picks up automatically.
  57. **Option B — Add accounts straight from your AI client:**
  58. Once the MCP server is configured, just ask your assistant to add an account — it uses the `imap_add_account` tool. For example:
  59. > "Add my IMAP account: host imap.gmail.com, port 993, user me@gmail.com, password …"
  60. No separate setup step required.
  61. ### Web-Based Setup Wizard (Recommended)
  62. After installation, run the setup wizard:
  63. ```bash
  64. npm run setup
  65. ```
  66. Or if installed globally:
  67. ```bash
  68. imap-setup
  69. ```
  70. Or directly via npx without installing:
  71. ```bash
  72. npx -p imap-mcp-server imap-setup
  73. ```
  74. This will:
  75. 1. Start a local web server
  76. 2. Open your browser to the setup wizard
  77. 3. Guide you through adding email accounts with pre-configured settings
  78. The wizard listens on `127.0.0.1` only, so nothing else on your network can
  79. reach it.
  80. #### Running the wizard on another machine (server, NAS, VM)
  81. **Recommended: SSH tunnel.** The wizard stays on loopback, and the connection is
  82. encrypted:
  83. ```bash
  84. ssh -L 3000:localhost:3000 my-server # then, on the server:
  85. imap-setup --no-open
  86. ```
  87. Open `http://localhost:3000` in your local browser.
  88. **Alternative: bind to the network.** Pass `--host` (or set `IMAP_MCP_BIND`):
  89. ```bash
  90. imap-setup --host 0.0.0.0 --no-open
  91. ```
  92. The wizard then requires an access token and prints a URL containing it, e.g.
  93. `http://my-server:3000/?token=…`. Open that URL; the token is exchanged for a
  94. session cookie and removed from the address bar. Requests without the token are
  95. refused, and so are cross-origin requests. Scripts can send
  96. `Authorization: Bearer <token>` instead. To use a fixed token rather than a
  97. random one per start, set `IMAP_MCP_WIZARD_TOKEN` (at least 16 characters); it is then not printed.
  98. The connection is plain HTTP, so anyone who can read your network traffic can
  99. see the token and the passwords you enter. Use this only on networks you trust,
  100. and prefer the SSH tunnel otherwise.
  101. | Variable | Default | Meaning |
  102. |---|---|---|
  103. | `IMAP_MCP_BIND` | `127.0.0.1` | Address the wizard binds to (`--host` takes precedence) |
  104. | `IMAP_MCP_WIZARD_TOKEN` | random per start | Access token when bound beyond loopback |
  105. | `PORT` | `3000` | Port for `npm run web` (`imap-setup` uses `--port`) |
  106. ### Overriding Credentials via Environment Variables
  107. You can override the username and password of an already-configured account at
  108. runtime with environment variables — useful when you inject secrets from a
  109. password manager or CI system instead of storing them in `accounts.json`.
  110. The variables are keyed by the account **name**, uppercased with every
  111. non-alphanumeric character replaced by `_`. For an account named `Work Gmail`
  112. (key `WORK_GMAIL`):
  113. | Variable | Overrides |
  114. | --- | --- |
  115. | `IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_USERNAME` | IMAP username (`user`) |
  116. | `IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD` | IMAP password |
  117. | `IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_USERNAME` | SMTP username (`smtp.user`) |
  118. | `IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_PASSWORD` | SMTP password |
  119. Notes:
  120. - Overrides apply **only to existing accounts**; if no account's normalized name
  121. matches, the variable is ignored.
  122. - They are applied **in memory only** — nothing is written back to
  123. `accounts.json`, and the values are used as-is (not re-encrypted).
  124. - Variables are **consumed at startup**: on server start they are captured into
  125. an AES-256-encrypted in-memory cache and removed from `process.env`, so the
  126. plaintext secret does not linger in the environment (where it could leak to
  127. child processes or diagnostics). Set them before launching the server.
  128. The setup wizard integrates with this: each credential field (IMAP password,
  129. IMAP username, SMTP username, SMTP password) has a **"Do not save to config; set
  130. later using an environment variable"** checkbox. When ticked, the value you enter
  131. is still used to test the connection, but it is not written to `accounts.json` —
  132. the wizard shows the exact variable name to export, and the account picks the
  133. credential up from that variable at runtime.
  134. - SMTP variables take effect only when the account already has an SMTP config.
  135. - Each variable takes effect independently; set only the ones you need.
  136. **If the variable is missing**, the account still holds the empty placeholder the
  137. wizard wrote. Rather than dialing out with a blank credential — which providers
  138. answer with a generic authentication failure that looks exactly like a wrong
  139. password — the server refuses the connection and names what to set:
  140. ```
  141. Account "Work Gmail" has IMAP credentials marked as environment-managed, but
  142. this variable was not set when the server started:
  143. IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD. Set it and restart the server, or
  144. store the credentials on the account via imap_update_account.
  145. ```
  146. Because the variables are read once at startup, setting one in an already-running
  147. shell has no effect until the server is restarted.
  148. ### Supported Email Providers
  149. The setup wizard includes pre-configured settings for:
  150. - Gmail / Google Workspace
  151. - Microsoft Outlook / Hotmail / Live
  152. - Yahoo Mail
  153. - Apple iCloud Mail
  154. - GMX
  155. - WEB.DE
  156. - IONOS (1&1)
  157. - ProtonMail (with Bridge)
  158. - Fastmail
  159. - Zoho Mail
  160. - AOL Mail
  161. - mailbox.org
  162. - Posteo
  163. - Custom IMAP servers
  164. ## Configuration
  165. ### Claude Code (CLI)
  166. #### Option A — via npx (no clone/build needed)
  167. ```bash
  168. claude mcp add imap -- npx -y imap-mcp-server
  169. ```
  170. This always runs the latest published version and requires no local build.
  171. #### Option B — from a local clone
  172. If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in the terminal, add the MCP server with a single command:
  173. **Step 1:** Make sure you have built the project first (see [Manual Installation](#manual-installation)).
  174. **Step 2:** Run this command in your terminal:
  175. ```bash
  176. claude mcp add imap -- node /absolute/path/to/imap-mcp-server/dist/index.js
  177. ```
  178. > **Important:** Replace `/absolute/path/to/imap-mcp-server` with the actual path where you cloned the repository. For example:
  179. > ```bash
  180. > # macOS/Linux example:
  181. > claude mcp add imap -- node /Users/yourname/imap-mcp-server/dist/index.js
  182. >
  183. > # Windows example:
  184. > claude mcp add imap -- node C:\Users\yourname\imap-mcp-server\dist\index.js
  185. > ```
  186. **Step 3:** Verify it was added:
  187. ```bash
  188. claude mcp list
  189. ```
  190. You should see `imap` in the list of configured MCP servers. That's it — the IMAP tools are now available in your Claude Code sessions.
  191. > **Tip:** If you want to remove the server later, run:
  192. > ```bash
  193. > claude mcp remove imap
  194. > ```
  195. ### Claude Desktop (GUI App)
  196. Add the IMAP MCP server to your Claude Desktop configuration file:
  197. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  198. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  199. **Option A — via npx (recommended, no clone/build needed):**
  200. ```json
  201. {
  202. "mcpServers": {
  203. "imap": {
  204. "command": "npx",
  205. "args": ["-y", "imap-mcp-server"],
  206. "env": {}
  207. }
  208. }
  209. }
  210. ```
  211. **Option B — from a local clone:**
  212. ```json
  213. {
  214. "mcpServers": {
  215. "imap": {
  216. "command": "node",
  217. "args": ["/path/to/imap-mcp-server/dist/index.js"],
  218. "env": {}
  219. }
  220. }
  221. }
  222. ```
  223. ### Restricting tool access (read-only mode / allowlist)
  224. By default all tools are exposed. You can restrict which tools the agent sees
  225. using two environment variables (set them under the `env` key of your MCP
  226. config). This is useful when you want to give an assistant **read-only** access
  227. to a mailbox, or expose only a hand-picked subset of tools.
  228. | Variable | Effect |
  229. | --- | --- |
  230. | `IMAP_MCP_READ_ONLY` | When truthy (`1`, `true`, `yes`, `on`), only the safe, read-only tools are registered — searching, reading, listing folders, unread counts, spam analysis. No tool that sends mail, deletes/moves messages, changes flags, or edits accounts is exposed. |
  231. | `IMAP_MCP_ENABLED_TOOLS` | Comma-separated allowlist of tool names — only these are registered. Names are case-insensitive and the `imap_` prefix is optional (`search_emails` ≡ `imap_search_emails`). When set, it takes precedence over `IMAP_MCP_READ_ONLY`. |
  232. **Example — read-only access:**
  233. ```json
  234. {
  235. "mcpServers": {
  236. "imap": {
  237. "command": "npx",
  238. "args": ["-y", "imap-mcp-server"],
  239. "env": { "IMAP_MCP_READ_ONLY": "true" }
  240. }
  241. }
  242. }
  243. ```
  244. **Example — explicit allowlist:**
  245. ```json
  246. {
  247. "mcpServers": {
  248. "imap": {
  249. "command": "npx",
  250. "args": ["-y", "imap-mcp-server"],
  251. "env": { "IMAP_MCP_ENABLED_TOOLS": "imap_search_emails,imap_get_email,imap_get_latest_emails" }
  252. }
  253. }
  254. }
  255. ```
  256. The read-only subset is: `imap_list_accounts`, `imap_connect`, `imap_disconnect`,
  257. `imap_test_account`, `imap_search_emails`, `imap_get_email`,
  258. `imap_get_latest_emails`, `imap_download_attachment`, `imap_find_thread_messages`,
  259. `imap_find_email_by_message_id`, `imap_list_folders`, `imap_folder_status`,
  260. `imap_get_unread_count`, `imap_check_spam`, `imap_domain_stats`,
  261. `imap_list_spam_domains`.
  262. ## Usage
  263. Once configured, the IMAP MCP server provides the following tools in Claude:
  264. > **Choosing an account.** For the email and folder tools, `accountId` is
  265. > **optional** and backward-compatible. You may instead pass `accountName`, and
  266. > if you only have a **single** account configured you can omit both — that
  267. > account is used by default. With multiple accounts and no selector, the tool
  268. > returns a clear error listing your options (`imap_list_accounts`).
  269. ### Account Management
  270. - **imap_add_account**: Add a new IMAP account
  271. ```
  272. Parameters:
  273. - name: Friendly name for the account
  274. - host: IMAP server hostname
  275. - port: Server port (default: 993)
  276. - user: Username
  277. - password: Password
  278. - tls: Use TLS/SSL (default: true)
  279. - allowStartTLS: When tls is false, set to false to also disable the
  280. opportunistic STARTTLS upgrade imapflow otherwise attempts whenever the
  281. server advertises it (validating the cert against `host` regardless of
  282. `tls`). Needed for providers that advertise STARTTLS on a hostname
  283. covered only by a shared/wildcard cert. Defaults to true.
  284. - sentFolder: Explicit Sent-folder name for sent-mail copies, e.g. "Gesendet"
  285. (optional — only needed when the server has no \Sent SPECIAL-USE folder
  286. and auto-detection fails)
  287. - defaultBcc: Optional BCC address(es) applied automatically to every
  288. outbound send, reply, forward, and draft for this account. Merged with
  289. any per-call `bcc` (duplicates removed case-insensitively)
  290. - allowedFrom: Optional list of additional sender identities permitted in
  291. outbound `From` headers. The account email and login are always allowed
  292. ```
  293. - **imap_update_account**: Update an existing account (fix SMTP settings, rename, etc.)
  294. ```
  295. Parameters:
  296. - accountId: ID of the account to update
  297. - name, host, port, user, password, tls, allowStartTLS, email: IMAP fields (all optional)
  298. - smtpHost, smtpPort, smtpSecure, smtpUser, smtpPassword: SMTP fields (optional)
  299. - saveToSent: Save sent emails to the Sent folder (optional)
  300. - sentFolder: Explicit Sent-folder override (optional). Pass an empty string
  301. to clear the override and re-enable auto-detection
  302. - defaultBcc: Optional default BCC address(es) (optional). Pass an empty
  303. string to clear
  304. - allowedFrom: Optional list of additional sender identities. Pass an empty
  305. array to clear
  306. ```
  307. `allowedFrom` is an application-level guardrail, not a hard security boundary:
  308. an agent with access to `imap_update_account` can change the allowed identities.
  309. The SMTP server must enforce the actual sender authorization policy. Sender
  310. mailbox addresses are matched case-insensitively; the supplied display name and
  311. address casing are preserved in the outbound `From` header. This applies to
  312. sending, drafts, replies, and forwards.
  313. - **imap_list_accounts**: List all configured accounts
  314. - **imap_remove_account**: Remove an account
  315. ```
  316. Parameters:
  317. - accountId: ID of the account to remove
  318. ```
  319. - **imap_connect**: Connect to an account
  320. ```
  321. Parameters:
  322. - accountId OR accountName: Account identifier
  323. ```
  324. - **imap_disconnect**: Disconnect from an account
  325. ```
  326. Parameters:
  327. - accountId: Account to disconnect
  328. ```
  329. ### Email Operations
  330. - **imap_search_emails**: Search for emails
  331. ```
  332. Parameters:
  333. - accountId: Account ID
  334. - folder: Folder name (default: INBOX; ignored when searchAllFolders is true)
  335. - searchAllFolders: Search across ALL folders at once (default: false).
  336. Skips Trash/Spam/Drafts and non-selectable folders by default. Use when a
  337. message may have been filed/moved/archived and you don't know its folder.
  338. - includeTrash, includeSpam, includeDrafts: Opt those noisy folders back into
  339. a searchAllFolders run (default: false each)
  340. - from, to, subject, body: Search criteria
  341. - since, before: Date filters
  342. - seen, flagged: Status filters
  343. - keywords: Match messages with ANY of these custom keywords (server-side OR).
  344. Read a mailbox's available custom keywords from `imap_folder_status`'s
  345. `customKeywords` field first.
  346. - unKeywords: Exclude messages with ANY of these custom keywords (result has
  347. NONE of them). Same keyword source as `keywords`.
  348. - limit: Max results (default: 50)
  349. - includeBody: Include parsed message body in the response (default: false).
  350. Fetches the RFC822 source once and parses it with mailparser, so you get
  351. uid + body in a single tool call instead of paying the N+1 cost of one
  352. `imap_get_email` per match. Body is rendered per `bodyFormat` and capped
  353. at `bodyMaxLength` per field.
  354. - bodyFormat: How to render the body when `includeBody` is true — `markdown`
  355. (default, clean Markdown via Turndown), `text`, `html`, or `auto`.
  356. - bodyMaxLength: Per-field cap when `includeBody` is true (default: 10000).
  357. ```
  358. > With `searchAllFolders`, results include a `folder` field per message plus
  359. > `foldersSearched`, and any folder that failed to open is reported in
  360. > `foldersErrored` (so a 0-result answer is never silently incomplete).
  361. >
  362. > `includeBody` is honored in the single-folder path only. For a
  363. > cross-folder sweep the lightweight header shape is preserved by design —
  364. > pulling RFC822 source for every match across many folders would multiply
  365. > bandwidth and parse cost. Follow up with `imap_get_email` for the specific
  366. > uids whose bodies you need.
  367. >
  368. > On some servers a "flagged"/starred message carries a custom keyword (e.g.
  369. > an Open-Xchange color label or Apple's `$MailFlagBit*`) instead of, or in
  370. > addition to, the `\Flagged` system flag — after any flagged search, check
  371. > each result's `customKeywords` field before concluding a message is or
  372. > isn't flagged.
  373. - **imap_get_email**: Get full email content
  374. ```
  375. Parameters:
  376. - accountId: Account ID
  377. - folder: Folder name
  378. - uid: Email UID
  379. - maxContentLength: Max characters for text/html body (default: 10000)
  380. - includeAttachmentText: Include text attachment previews (default: true)
  381. - maxAttachmentTextChars: Max characters per text attachment (default: 100000)
  382. ```
  383. - **imap_get_latest_emails**: Get recent emails
  384. ```
  385. Parameters:
  386. - accountId: Account ID
  387. - folder: Folder name (default: INBOX)
  388. - count: Number of emails (default: 10)
  389. - includeBody: Include parsed message body (default: false). Same semantics
  390. as the `includeBody` option on `imap_search_emails` — one round-trip
  391. instead of N×`imap_get_email`.
  392. - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.
  393. - bodyMaxLength: Per-field cap (default: 10000).
  394. ```
  395. - **imap_mark_as_read/unread**: Change email read status
  396. ```
  397. Parameters:
  398. - accountId: Account ID
  399. - folder: Folder name
  400. - uid: Email UID, OR an array of UIDs to flag in one call. Batch uses a
  401. single IMAP STORE so the operation is atomic at the server level — all
  402. UIDs are flagged, or none. Useful when triaging many messages at once.
  403. ```
  404. - **imap_flag_email/unflag_email**: Star/unstar an email (sets or clears the IMAP \Flagged system flag — shows as a "star" in Gmail and Apple Mail). Some servers/clients (Open-Xchange, Apple Mail) also set a separate custom keyword (e.g. `$cl_N`, `$MailFlagBit*`) when flagging; unflag only clears `\Flagged`, so if a message still shows as flagged, check `customKeywords` via `imap_get_email` and clear it with `imap_remove_keyword`.
  405. ```
  406. Parameters:
  407. - accountId: Account ID
  408. - folder: Folder name
  409. - uid: Email UID
  410. ```
  411. - **imap_add_keyword/remove_keyword**: Set or clear an arbitrary *custom* (non-system) IMAP keyword/label on an email, passed through verbatim (e.g. provider color labels like Open-Xchange's `$cl_1`..`$cl_10` or Apple Mail's `$MailFlagBit0`..`$MailFlagBit2`, or any other custom keyword). Backslash-prefixed system flags (e.g. `\Flagged`, `\Seen`, `\Deleted`) are rejected — use the dedicated flag/read tools for those. Not every server permits custom-keyword changes (see the mailbox's PERMANENTFLAGS); if the server rejects or silently ignores the change, the call fails instead of reporting success.
  412. ```
  413. Parameters:
  414. - accountId: Account ID
  415. - folder: Folder name
  416. - uid: Email UID
  417. - keyword: IMAP keyword to set/remove (e.g. "$cl_3")
  418. ```
  419. - **imap_delete_email**: Delete an email
  420. ```
  421. Parameters:
  422. - accountId: Account ID
  423. - folder: Folder name
  424. - uid: Email UID
  425. ```
  426. - **imap_move_email**: Move an email from one folder to another
  427. ```
  428. Parameters:
  429. - accountId: Account ID
  430. - folder: Source folder name (default: INBOX)
  431. - uid: Email UID, OR an array of UIDs to move in one call. Batch moves are
  432. attributed per-uid in the response (`results[]` with per-uid `uidMap`
  433. and any errors). Single-uid calls return the legacy response shape.
  434. - targetFolder: Destination folder name
  435. - createDestinationIfMissing: Create the destination folder if it does not exist (default: false)
  436. ```
  437. - **imap_find_thread_messages**: Find inbox messages that belong to the same conversation threads as messages already sorted into another folder. Uses RFC 3501 HEADER search on In-Reply-To and References — works on any IMAP server.
  438. ```
  439. Parameters:
  440. - accountId: Account ID
  441. - sourceFolder: Folder containing the already-sorted thread messages
  442. - searchFolder: Folder to search for related messages (default: INBOX)
  443. - searchReferences: Also match the References header for multi-level threads (default: true)
  444. - includeBody: Include parsed message body for each found thread message
  445. (default: false). Same semantics as the `includeBody` option on
  446. `imap_search_emails` — one round-trip instead of N×`imap_get_email`.
  447. - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.
  448. - bodyMaxLength: Per-field cap (default: 10000).
  449. ```
  450. - **imap_download_attachment**: Download an email attachment (returns images inline, extracts text from PDFs, or saves to downloads directory)
  451. ```
  452. Parameters:
  453. - accountId: Account ID
  454. - folder: Folder name (default: INBOX)
  455. - uid: Email UID
  456. - filename: Attachment filename or contentId (as listed by imap_get_email; NFC/NFD
  457. spellings of accented characters are treated as equal, and a contentId may
  458. be passed with or without angle brackets)
  459. - savePath: Optional file path to save the attachment to
  460. - extractText: For PDFs, extract and return text content inline (default: true)
  461. ```
  462. - **imap_bulk_delete**: Delete multiple emails at once with chunking and auto-reconnection
  463. ```
  464. Parameters:
  465. - accountId: Account ID
  466. - folder: Folder name (default: INBOX)
  467. - uids: Array of email UIDs to delete
  468. - chunkSize: Emails to delete per batch (default: 50)
  469. ```
  470. - **imap_bulk_delete_by_search**: Search for emails matching criteria and delete them all
  471. ```
  472. Parameters:
  473. - accountId: Account ID
  474. - folder: Folder name (default: INBOX)
  475. - from, to, subject: Search criteria (optional)
  476. - before, since: Date filters (optional)
  477. - chunkSize: Emails to delete per batch (default: 50)
  478. - dryRun: Preview what would be deleted without deleting (default: false)
  479. ```
  480. At least one concrete criterion (`from`, `to`, `subject`, `before`, or `since`)
  481. is required — a call with no criteria is refused, so it can never match and
  482. delete an entire folder. On servers whose SEARCH is broken (see
  483. Troubleshooting → Search returns nothing) this tool, `imap_delete_spam` and
  484. `imap_delete_by_domain` return an error instead of deleting from a
  485. client-side match.
  486. - **imap_send_email**: Send a new email
  487. ```
  488. Parameters:
  489. - accountId: Account ID to send from
  490. - from: Sender identity (optional). Must match the account email/login or an
  491. address configured in `allowedFrom`
  492. - to: Recipient email address(es) — an array, or a single comma-separated string
  493. - subject: Email subject
  494. - text: Plain text content (optional)
  495. - html: HTML content (optional)
  496. - cc: CC recipients (optional)
  497. - bcc: BCC recipients (optional)
  498. - replyTo: Reply-to address (optional)
  499. - attachments: Array of attachments (optional)
  500. - filename: Attachment filename
  501. - content: Base64 encoded content; provide exactly one of `content` or `path`
  502. - path: Readable local file path to attach; provide exactly one of `path` or `content`
  503. - contentType: MIME type (optional; detected from the filename extension when omitted)
  504. - contentDisposition: "attachment" (default) or "inline" — use "inline" for images shown in the HTML body via cid:
  505. - cid: Content-ID for inline attachments; must match the `cid:` value used in an `<img src="cid:...">` tag in `html`
  506. - dryRun: Validate attachments and compose MIME without sending or saving to Sent (optional, default: false)
  507. ```
  508. Attachments are validated before SMTP is contacted. Invalid base64, unreadable
  509. paths, missing filenames, ambiguous sources, and inline attachments without
  510. `cid` fail fast. Successful sends and dry-runs return `attachmentCount` and
  511. safe `attachmentDiagnostics`: filename, MIME type, size, source, disposition,
  512. and cid. Diagnostics omit bytes, raw MIME, and local file paths.
  513. For large files, upload with `imap_upload_file` first and pass its returned
  514. local `path`; for inline images, set `contentDisposition: "inline"` and a
  515. matching `cid`.
  516. After sending, a copy is saved to the account's Sent folder (unless
  517. `saveToSent` is disabled on the account). The folder is resolved via the
  518. account's `sentFolder` override → the server's `\Sent` SPECIAL-USE flag →
  519. a list of known localized names ("Sent", "Gesendet", "Éléments envoyés", …).
  520. The response reports the outcome: `savedToSent` (boolean), `sentFolder`
  521. (the folder used), and — when the save fails — `sentSaveError` explaining
  522. why, instead of failing silently. The same applies to `imap_reply_to_email`
  523. and `imap_forward_email`.
  524. When the account has `defaultBcc` configured, those address(es) are always
  525. BCC'd on send, reply, forward, and draft (merged with any per-call `bcc`;
  526. duplicates removed case-insensitively). The Bcc header is kept in the MIME
  527. stored for drafts and Sent-folder copies so mail clients show it.
  528. - **imap_save_draft**: Save an email as a draft (no send). Takes the same fields as `imap_send_email`, plus `inReplyTo`, `references`, and an optional `folder` override for the Drafts folder.
  529. - **imap_reply_to_email**: Reply to an existing email
  530. ```
  531. Parameters:
  532. - accountId: Account ID
  533. - folder: Folder containing the original email
  534. - uid: UID of the email to reply to
  535. - text: Plain text reply content (optional)
  536. - html: HTML reply content (optional)
  537. - replyAll: Reply to all recipients (default: false)
  538. - bcc: BCC recipients (optional; merged with account defaultBcc)
  539. - attachments: Array of attachments (optional, same shape as imap_send_email, including contentDisposition/cid for inline images)
  540. ```
  541. - **imap_forward_email**: Forward an existing email
  542. ```
  543. Parameters:
  544. - accountId: Account ID
  545. - folder: Folder containing the original email
  546. - uid: UID of the email to forward
  547. - to: Forward to email address(es)
  548. - text: Additional text to include (optional)
  549. - bcc: BCC recipients (optional; merged with account defaultBcc)
  550. - includeAttachments: Include original attachments (default: true)
  551. ```
  552. ### Folder Operations
  553. - **imap_list_folders**: List all folders
  554. ```
  555. Parameters:
  556. - accountId: Account ID
  557. ```
  558. Each folder includes its `attributes` (raw IMAP LIST flags) and, when the
  559. server advertises it, `specialUse` — the RFC 6154 role (`\Sent`, `\Drafts`,
  560. `\Trash`, `\Junk`, `\Archive`) that identifies a folder independent of its
  561. localized display name (e.g. "Gesendet" carries `specialUse: "\Sent"`).
  562. - **imap_folder_status**: Get folder information
  563. ```
  564. Parameters:
  565. - accountId: Account ID
  566. - folder: Folder name
  567. Returns:
  568. - messages: { total, new, unseen } — from IMAP STATUS
  569. - uidvalidity, uidnext
  570. - flags, permanentFlags: string arrays
  571. - customKeywords: the mailbox's non-system keywords, usable as the
  572. `keywords` / `unKeywords` input of imap_search_emails
  573. ```
  574. - **imap_create_folder**: Create a new IMAP folder/mailbox. Most servers also create any missing parent folders. Returns success even if the folder already exists.
  575. ```
  576. Parameters:
  577. - accountId: Account ID
  578. - folder: Full folder path to create (e.g. "Archives/2026/2026-05" or "INBOX.Archive")
  579. ```
  580. - **imap_get_unread_count**: Count unread emails
  581. ```
  582. Parameters:
  583. - accountId: Account ID
  584. - folders: Specific folders (optional)
  585. ```
  586. ## Security
  587. - Credentials are encrypted using AES-256-CBC encryption
  588. - Encryption keys are stored separately in `~/.imap-mcp/.key`
  589. - Account configurations are stored in `~/.imap-mcp/accounts.json`
  590. - The store directory, `.key`, and `accounts.json` are written owner-only
  591. (`0700`/`0600`) so other local users cannot read the key or the credentials
  592. - The web setup wizard's HTTP API never returns stored passwords to the browser
  593. - Downloaded attachments are confined to the downloads directory; sender-supplied
  594. filenames cannot write outside it
  595. - Never commit or share your encryption key or account configurations
  596. ## Development
  597. ### Running in Development Mode
  598. ```bash
  599. npm run dev
  600. ```
  601. ### Building
  602. ```bash
  603. npm run build
  604. ```
  605. ### Project Structure
  606. ```
  607. src/
  608. ├── index.ts # MCP server entry point
  609. ├── services/
  610. │ ├── imap-service.ts # IMAP connection management
  611. │ ├── smtp-service.ts # SMTP service for sending emails
  612. │ └── account-manager.ts # Account configuration
  613. ├── tools/
  614. │ ├── index.ts # Tool registration
  615. │ ├── account-tools.ts # Account management tools
  616. │ ├── email-tools.ts # Email operation tools (including send/reply/forward)
  617. │ └── folder-tools.ts # Folder operation tools
  618. └── types/
  619. └── index.ts # TypeScript type definitions
  620. ```
  621. ## Example Usage in Claude
  622. 1. **Add an account:**
  623. "Add my Gmail account with username john@gmail.com"
  624. 2. **Check new emails:**
  625. "Show me the latest 5 emails from my Gmail account"
  626. 3. **Search emails:**
  627. "Search for emails from boss@company.com in the last week"
  628. 4. **Send an email:**
  629. "Send an email to client@example.com with subject 'Project Update'"
  630. 5. **Reply to emails:**
  631. "Reply to the latest email from my boss"
  632. 6. **Forward emails:**
  633. "Forward the email with subject 'Meeting Notes' to team@company.com"
  634. 7. **Move an email:**
  635. "Move the invoice email from INBOX to my Taxes folder"
  636. 8. **Manage folders:**
  637. "List all folders in my email account and show unread counts"
  638. ## Troubleshooting
  639. ### Connection Issues
  640. - Ensure your IMAP server settings are correct
  641. - Check if your email provider requires app-specific passwords
  642. - Verify that IMAP is enabled in your email account settings
  643. - For sending emails, ensure your account has SMTP access enabled
  644. ### Recipients arriving as `["a@x.com","b@y.com"]`
  645. `to`, `cc`, `bcc`, `references` and `uid` accept either a single value or an
  646. array. In JSON Schema that is an `anyOf`, and some MCP clients drop the `anyOf`
  647. before showing the schema to the model — the field then looks untyped or
  648. string-typed, and the client serializes the model's array into a string. The
  649. server used to pass that string straight to nodemailer, which folded the
  650. literal `[` and `]` into the first and last address, so every recipient was
  651. rejected by the receiving mail server (issue #127).
  652. The server now detects a stringified array and restores it, both when
  653. validating tool input and again before composing the message, and logs a
  654. warning to stderr naming the field. Nothing needs to change on your side. If
  655. you want to bypass the client behavior entirely, pass recipients as one
  656. comma-separated string: `"Alice <alice@example.com>, Bob <bob@example.org>"`.
  657. ### Search returns nothing although the folder has mail (Strato)
  658. Since mid-2026 Strato's IMAP server (`imap.strato.com`) answers every SEARCH
  659. command with an empty result, while FETCH still works (issue #138). The server
  660. detects this: when a SEARCH comes back empty for a folder that is not empty and
  661. `SEARCH ALL` is empty as well, it fetches the envelopes and applies the
  662. criteria itself. `imap_search_emails`, `imap_find_thread_messages`, the unread counts and the
  663. spam analysis keep working; `imap_get_latest_emails` never needed SEARCH.
  664. Limits of the fallback:
  665. - It is slower — every envelope of the folder is downloaded per search.
  666. - A `body` search downloads and parses each remaining candidate, so it is
  667. refused above 2000 candidates; narrow it with `since`/`from`/`subject`.
  668. - Deleting tools (`imap_bulk_delete_by_search`, `imap_delete_spam`,
  669. `imap_delete_by_domain`) do **not** use it and return an error instead. Find
  670. the messages with `imap_search_emails` and delete their UIDs with
  671. `imap_bulk_delete`.
  672. ### SMTP Configuration
  673. The server automatically configures SMTP settings based on your IMAP provider. If you need custom SMTP settings, you can specify them when adding an account:
  674. ```json
  675. {
  676. "smtp": {
  677. "host": "smtp.example.com",
  678. "port": 587,
  679. "secure": false
  680. }
  681. }
  682. ```
  683. ### Common IMAP Settings
  684. - **Gmail**:
  685. - Host: imap.gmail.com
  686. - Port: 993
  687. - Requires app-specific password
  688. - **Outlook/Hotmail**:
  689. - Host: outlook.office365.com
  690. - Port: 993
  691. - **Yahoo**:
  692. - Host: imap.mail.yahoo.com
  693. - Port: 993
  694. - Requires app-specific password
  695. ## License
  696. MIT
  697. ## Contributing
  698. Contributions are welcome! Please feel free to submit a Pull Request.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.