{
"markdown": "# IMAP MCP Server\n\nA powerful Model Context Protocol (MCP) server that provides seamless IMAP email integration with secure account management and connection pooling.\n\n## Features\n\n- π **Secure Account Management**: Encrypted credential storage with AES-256 encryption\n- π **Connection Pooling**: Efficient IMAP connection management\n- π§ **Comprehensive Email Operations**: Search, read, move, mark, delete, and bulk delete emails\n- βοΈ **Email Sending**: Send, reply, and forward emails via SMTP\n- π **Folder Management**: List folders, check status, get unread counts\n- π **Multiple Account Support**: Manage multiple IMAP accounts simultaneously\n- π‘οΈ **Type-Safe**: Built with TypeScript for reliability\n- π **Web-Based Setup Wizard**: Easy account configuration with provider presets\n- π± **15+ Email Providers**: Pre-configured settings for Gmail, Outlook, Yahoo, and more\n- π **Auto SMTP Configuration**: Automatic SMTP settings based on IMAP provider\n\n## Installation\n\n> **Requires Node.js 22.12 or newer.** Node 18 and 20 have both reached\n> end-of-life, and several of this package's dependencies no longer support\n> them. Check yours with `node --version`.\n\n### Run via npx (No Installation Required)\n\nOnce published to npm, you can run the server directly without cloning or building anything β `npx` downloads the prebuilt package and runs it:\n\n```bash\nnpx -y imap-mcp-server\n```\n\nThis is the easiest way to use the server in an MCP client (see [Configuration](#configuration) for ready-to-paste `npx` configs).\n\n### Quick Install (Recommended)\n\n#### macOS/Linux:\n```bash\ncurl -fsSL https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.sh | bash\n```\n\n#### Windows (PowerShell as Administrator):\n```powershell\niwr -useb https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.ps1 | iex\n```\n\n### Manual Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/nikolausm/imap-mcp-server.git\ncd imap-mcp-server\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Build the project:\n```bash\nnpm run build\n```\n\n## Account Setup\n\nAccounts 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.\n\n### Setting Up Accounts in npx Mode\n\nIf you run the server via `npx` (no clone), you have two ways to add accounts:\n\n**Option A β Run the setup wizard directly via npx (no install needed):**\n\n```bash\nnpx -p imap-mcp-server imap-setup\n```\n\nThis 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.\n\n**Option B β Add accounts straight from your AI client:**\n\nOnce the MCP server is configured, just ask your assistant to add an account β it uses the `imap_add_account` tool. For example:\n\n> \"Add my IMAP account: host imap.gmail.com, port 993, user me@gmail.com, password β¦\"\n\nNo separate setup step required.\n\n### Web-Based Setup Wizard (Recommended)\n\nAfter installation, run the setup wizard:\n\n```bash\nnpm run setup\n```\n\nOr if installed globally:\n\n```bash\nimap-setup\n```\n\nOr directly via npx without installing:\n\n```bash\nnpx -p imap-mcp-server imap-setup\n```\n\nThis will:\n1. Start a local web server\n2. Open your browser to the setup wizard\n3. Guide you through adding email accounts with pre-configured settings\n\n### Overriding Credentials via Environment Variables\n\nYou can override the username and password of an already-configured account at\nruntime with environment variables β useful when you inject secrets from a\npassword manager or CI system instead of storing them in `accounts.json`.\n\nThe variables are keyed by the account **name**, uppercased with every\nnon-alphanumeric character replaced by `_`. For an account named `Work Gmail`\n(key `WORK_GMAIL`):\n\n| Variable | Overrides |\n| --- | --- |\n| `IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_USERNAME` | IMAP username (`user`) |\n| `IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD` | IMAP password |\n| `IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_USERNAME` | SMTP username (`smtp.user`) |\n| `IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_PASSWORD` | SMTP password |\n\nNotes:\n- Overrides apply **only to existing accounts**; if no account's normalized name\n matches, the variable is ignored.\n- They are applied **in memory only** β nothing is written back to\n `accounts.json`, and the values are used as-is (not re-encrypted).\n- Variables are **consumed at startup**: on server start they are captured into\n an AES-256-encrypted in-memory cache and removed from `process.env`, so the\n plaintext secret does not linger in the environment (where it could leak to\n child processes or diagnostics). Set them before launching the server.\n\nThe setup wizard integrates with this: each credential field (IMAP password,\nIMAP username, SMTP username, SMTP password) has a **\"Do not save to config; set\nlater using an environment variable\"** checkbox. When ticked, the value you enter\nis still used to test the connection, but it is not written to `accounts.json` β\nthe wizard shows the exact variable name to export, and the account picks the\ncredential up from that variable at runtime.\n- SMTP variables take effect only when the account already has an SMTP config.\n- Each variable takes effect independently; set only the ones you need.\n\n**If the variable is missing**, the account still holds the empty placeholder the\nwizard wrote. Rather than dialing out with a blank credential β which providers\nanswer with a generic authentication failure that looks exactly like a wrong\npassword β the server refuses the connection and names what to set:\n\n```\nAccount \"Work Gmail\" has IMAP credentials marked as environment-managed, but\nthis variable was not set when the server started:\nIMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD. Set it and restart the server, or\nstore the credentials on the account via imap_update_account.\n```\n\nBecause the variables are read once at startup, setting one in an already-running\nshell has no effect until the server is restarted.\n\n### Supported Email Providers\n\nThe setup wizard includes pre-configured settings for:\n- Gmail / Google Workspace\n- Microsoft Outlook / Hotmail / Live\n- Yahoo Mail\n- Apple iCloud Mail\n- GMX\n- WEB.DE\n- IONOS (1&1)\n- ProtonMail (with Bridge)\n- Fastmail\n- Zoho Mail\n- AOL Mail\n- mailbox.org\n- Posteo\n- Custom IMAP servers\n\n## Configuration\n\n### Claude Code (CLI)\n\n#### Option A β via npx (no clone/build needed)\n\n```bash\nclaude mcp add imap -- npx -y imap-mcp-server\n```\n\nThis always runs the latest published version and requires no local build.\n\n#### Option B β from a local clone\n\nIf you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in the terminal, add the MCP server with a single command:\n\n**Step 1:** Make sure you have built the project first (see [Manual Installation](#manual-installation)).\n\n**Step 2:** Run this command in your terminal:\n\n```bash\nclaude mcp add imap -- node /absolute/path/to/imap-mcp-server/dist/index.js\n```\n\n> **Important:** Replace `/absolute/path/to/imap-mcp-server` with the actual path where you cloned the repository. For example:\n> ```bash\n> # macOS/Linux example:\n> claude mcp add imap -- node /Users/yourname/imap-mcp-server/dist/index.js\n>\n> # Windows example:\n> claude mcp add imap -- node C:\\Users\\yourname\\imap-mcp-server\\dist\\index.js\n> ```\n\n**Step 3:** Verify it was added:\n\n```bash\nclaude mcp list\n```\n\nYou should see `imap` in the list of configured MCP servers. That's it β the IMAP tools are now available in your Claude Code sessions.\n\n> **Tip:** If you want to remove the server later, run:\n> ```bash\n> claude mcp remove imap\n> ```\n\n### Claude Desktop (GUI App)\n\nAdd the IMAP MCP server to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n**Option A β via npx (recommended, no clone/build needed):**\n\n```json\n{\n \"mcpServers\": {\n \"imap\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"imap-mcp-server\"],\n \"env\": {}\n }\n }\n}\n```\n\n**Option B β from a local clone:**\n\n```json\n{\n \"mcpServers\": {\n \"imap\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/imap-mcp-server/dist/index.js\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Restricting tool access (read-only mode / allowlist)\n\nBy default all tools are exposed. You can restrict which tools the agent sees\nusing two environment variables (set them under the `env` key of your MCP\nconfig). This is useful when you want to give an assistant **read-only** access\nto a mailbox, or expose only a hand-picked subset of tools.\n\n| Variable | Effect |\n| --- | --- |\n| `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. |\n| `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`. |\n\n**Example β read-only access:**\n\n```json\n{\n \"mcpServers\": {\n \"imap\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"imap-mcp-server\"],\n \"env\": { \"IMAP_MCP_READ_ONLY\": \"true\" }\n }\n }\n}\n```\n\n**Example β explicit allowlist:**\n\n```json\n{\n \"mcpServers\": {\n \"imap\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"imap-mcp-server\"],\n \"env\": { \"IMAP_MCP_ENABLED_TOOLS\": \"imap_search_emails,imap_get_email,imap_get_latest_emails\" }\n }\n }\n}\n```\n\nThe read-only subset is: `imap_list_accounts`, `imap_connect`, `imap_disconnect`,\n`imap_test_account`, `imap_search_emails`, `imap_get_email`,\n`imap_get_latest_emails`, `imap_download_attachment`, `imap_find_thread_messages`,\n`imap_find_email_by_message_id`, `imap_list_folders`, `imap_folder_status`,\n`imap_get_unread_count`, `imap_check_spam`, `imap_domain_stats`,\n`imap_list_spam_domains`.\n\n## Usage\n\nOnce configured, the IMAP MCP server provides the following tools in Claude:\n\n> **Choosing an account.** For the email and folder tools, `accountId` is\n> **optional** and backward-compatible. You may instead pass `accountName`, and\n> if you only have a **single** account configured you can omit both β that\n> account is used by default. With multiple accounts and no selector, the tool\n> returns a clear error listing your options (`imap_list_accounts`).\n\n### Account Management\n\n- **imap_add_account**: Add a new IMAP account\n ```\n Parameters:\n - name: Friendly name for the account\n - host: IMAP server hostname\n - port: Server port (default: 993)\n - user: Username\n - password: Password\n - tls: Use TLS/SSL (default: true)\n - sentFolder: Explicit Sent-folder name for sent-mail copies, e.g. \"Gesendet\"\n (optional β only needed when the server has no \\Sent SPECIAL-USE folder\n and auto-detection fails)\n - defaultBcc: Optional BCC address(es) applied automatically to every\n outbound send, reply, forward, and draft for this account. Merged with\n any per-call `bcc` (duplicates removed case-insensitively)\n ```\n\n- **imap_update_account**: Update an existing account (fix SMTP settings, rename, etc.)\n ```\n Parameters:\n - accountId: ID of the account to update\n - name, host, port, user, password, tls, email: IMAP fields (all optional)\n - smtpHost, smtpPort, smtpSecure, smtpUser, smtpPassword: SMTP fields (optional)\n - saveToSent: Save sent emails to the Sent folder (optional)\n - sentFolder: Explicit Sent-folder override (optional). Pass an empty string\n to clear the override and re-enable auto-detection\n - defaultBcc: Optional default BCC address(es) (optional). Pass an empty\n string to clear\n ```\n\n- **imap_list_accounts**: List all configured accounts\n\n- **imap_remove_account**: Remove an account\n ```\n Parameters:\n - accountId: ID of the account to remove\n ```\n\n- **imap_connect**: Connect to an account\n ```\n Parameters:\n - accountId OR accountName: Account identifier\n ```\n\n- **imap_disconnect**: Disconnect from an account\n ```\n Parameters:\n - accountId: Account to disconnect\n ```\n\n### Email Operations\n\n- **imap_search_emails**: Search for emails\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name (default: INBOX; ignored when searchAllFolders is true)\n - searchAllFolders: Search across ALL folders at once (default: false).\n Skips Trash/Spam/Drafts and non-selectable folders by default. Use when a\n message may have been filed/moved/archived and you don't know its folder.\n - includeTrash, includeSpam, includeDrafts: Opt those noisy folders back into\n a searchAllFolders run (default: false each)\n - from, to, subject, body: Search criteria\n - since, before: Date filters\n - seen, flagged: Status filters\n - keywords: Match messages with ANY of these custom keywords (server-side OR).\n Read a mailbox's available custom keywords from `imap_folder_status`'s\n `customKeywords` field first.\n - unKeywords: Exclude messages with ANY of these custom keywords (result has\n NONE of them). Same keyword source as `keywords`.\n - limit: Max results (default: 50)\n - includeBody: Include parsed message body in the response (default: false).\n Fetches the RFC822 source once and parses it with mailparser, so you get\n uid + body in a single tool call instead of paying the N+1 cost of one\n `imap_get_email` per match. Body is rendered per `bodyFormat` and capped\n at `bodyMaxLength` per field.\n - bodyFormat: How to render the body when `includeBody` is true β `markdown`\n (default, clean Markdown via Turndown), `text`, `html`, or `auto`.\n - bodyMaxLength: Per-field cap when `includeBody` is true (default: 10000).\n ```\n > With `searchAllFolders`, results include a `folder` field per message plus\n > `foldersSearched`, and any folder that failed to open is reported in\n > `foldersErrored` (so a 0-result answer is never silently incomplete).\n >\n > `includeBody` is honored in the single-folder path only. For a\n > cross-folder sweep the lightweight header shape is preserved by design β\n > pulling RFC822 source for every match across many folders would multiply\n > bandwidth and parse cost. Follow up with `imap_get_email` for the specific\n > uids whose bodies you need.\n >\n > On some servers a \"flagged\"/starred message carries a custom keyword (e.g.\n > an Open-Xchange color label or Apple's `$MailFlagBit*`) instead of, or in\n > addition to, the `\\Flagged` system flag β after any flagged search, check\n > each result's `customKeywords` field before concluding a message is or\n > isn't flagged.\n\n- **imap_get_email**: Get full email content\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name\n - uid: Email UID\n - maxContentLength: Max characters for text/html body (default: 10000)\n - includeAttachmentText: Include text attachment previews (default: true)\n - maxAttachmentTextChars: Max characters per text attachment (default: 100000)\n ```\n\n- **imap_get_latest_emails**: Get recent emails\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name (default: INBOX)\n - count: Number of emails (default: 10)\n - includeBody: Include parsed message body (default: false). Same semantics\n as the `includeBody` option on `imap_search_emails` β one round-trip\n instead of NΓ`imap_get_email`.\n - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.\n - bodyMaxLength: Per-field cap (default: 10000).\n ```\n\n- **imap_mark_as_read/unread**: Change email read status\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name\n - uid: Email UID, OR an array of UIDs to flag in one call. Batch uses a\n single IMAP STORE so the operation is atomic at the server level β all\n UIDs are flagged, or none. Useful when triaging many messages at once.\n ```\n\n- **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`.\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name\n - uid: Email UID\n ```\n\n- **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.\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name\n - uid: Email UID\n - keyword: IMAP keyword to set/remove (e.g. \"$cl_3\")\n ```\n\n- **imap_delete_email**: Delete an email\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name\n - uid: Email UID\n ```\n\n- **imap_move_email**: Move an email from one folder to another\n ```\n Parameters:\n - accountId: Account ID\n - folder: Source folder name (default: INBOX)\n - uid: Email UID, OR an array of UIDs to move in one call. Batch moves are\n attributed per-uid in the response (`results[]` with per-uid `uidMap`\n and any errors). Single-uid calls return the legacy response shape.\n - targetFolder: Destination folder name\n - createDestinationIfMissing: Create the destination folder if it does not exist (default: false)\n ```\n\n- **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.\n ```\n Parameters:\n - accountId: Account ID\n - sourceFolder: Folder containing the already-sorted thread messages\n - searchFolder: Folder to search for related messages (default: INBOX)\n - searchReferences: Also match the References header for multi-level threads (default: true)\n - includeBody: Include parsed message body for each found thread message\n (default: false). Same semantics as the `includeBody` option on\n `imap_search_emails` β one round-trip instead of NΓ`imap_get_email`.\n - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.\n - bodyMaxLength: Per-field cap (default: 10000).\n ```\n\n- **imap_download_attachment**: Download an email attachment (returns images inline, extracts text from PDFs, or saves to downloads directory)\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name (default: INBOX)\n - uid: Email UID\n - filename: Attachment filename or contentId\n - savePath: Optional file path to save the attachment to\n - extractText: For PDFs, extract and return text content inline (default: true)\n ```\n\n- **imap_bulk_delete**: Delete multiple emails at once with chunking and auto-reconnection\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name (default: INBOX)\n - uids: Array of email UIDs to delete\n - chunkSize: Emails to delete per batch (default: 50)\n ```\n\n- **imap_bulk_delete_by_search**: Search for emails matching criteria and delete them all\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name (default: INBOX)\n - from, to, subject: Search criteria (optional)\n - before, since: Date filters (optional)\n - chunkSize: Emails to delete per batch (default: 50)\n - dryRun: Preview what would be deleted without deleting (default: false)\n ```\n At least one concrete criterion (`from`, `to`, `subject`, `before`, or `since`)\n is required β a call with no criteria is refused, so it can never match and\n delete an entire folder.\n\n- **imap_send_email**: Send a new email\n ```\n Parameters:\n - accountId: Account ID to send from\n - to: Recipient email address(es) β an array, or a single comma-separated string\n - subject: Email subject\n - text: Plain text content (optional)\n - html: HTML content (optional)\n - cc: CC recipients (optional)\n - bcc: BCC recipients (optional)\n - replyTo: Reply-to address (optional)\n - attachments: Array of attachments (optional)\n - filename: Attachment filename\n - content: Base64 encoded content\n - path: File path to attach\n - contentType: MIME type\n - contentDisposition: \"attachment\" (default) or \"inline\" β use \"inline\" for images shown in the HTML body via cid:\n - cid: Content-ID for inline attachments; must match the `cid:` value used in an `![](\"cid:...\")
` tag in `html`\n ```\n After sending, a copy is saved to the account's Sent folder (unless\n `saveToSent` is disabled on the account). The folder is resolved via the\n account's `sentFolder` override β the server's `\\Sent` SPECIAL-USE flag β\n a list of known localized names (\"Sent\", \"Gesendet\", \"ΓlΓ©ments envoyΓ©s\", β¦).\n The response reports the outcome: `savedToSent` (boolean), `sentFolder`\n (the folder used), and β when the save fails β `sentSaveError` explaining\n why, instead of failing silently. The same applies to `imap_reply_to_email`\n and `imap_forward_email`.\n\n When the account has `defaultBcc` configured, those address(es) are always\n BCC'd on send, reply, forward, and draft (merged with any per-call `bcc`;\n duplicates removed case-insensitively). The Bcc header is kept in the MIME\n stored for drafts and Sent-folder copies so mail clients show it.\n\n- **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.\n\n- **imap_reply_to_email**: Reply to an existing email\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder containing the original email\n - uid: UID of the email to reply to\n - text: Plain text reply content (optional)\n - html: HTML reply content (optional)\n - replyAll: Reply to all recipients (default: false)\n - bcc: BCC recipients (optional; merged with account defaultBcc)\n - attachments: Array of attachments (optional, same shape as imap_send_email, including contentDisposition/cid for inline images)\n ```\n\n- **imap_forward_email**: Forward an existing email\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder containing the original email\n - uid: UID of the email to forward\n - to: Forward to email address(es)\n - text: Additional text to include (optional)\n - bcc: BCC recipients (optional; merged with account defaultBcc)\n - includeAttachments: Include original attachments (default: true)\n ```\n\n### Folder Operations\n\n- **imap_list_folders**: List all folders\n ```\n Parameters:\n - accountId: Account ID\n ```\n Each folder includes its `attributes` (raw IMAP LIST flags) and, when the\n server advertises it, `specialUse` β the RFC 6154 role (`\\Sent`, `\\Drafts`,\n `\\Trash`, `\\Junk`, `\\Archive`) that identifies a folder independent of its\n localized display name (e.g. \"Gesendet\" carries `specialUse: \"\\Sent\"`).\n\n- **imap_folder_status**: Get folder information\n ```\n Parameters:\n - accountId: Account ID\n - folder: Folder name\n\n Returns:\n - messages: { total, new, unseen } β from IMAP STATUS\n - uidvalidity, uidnext\n - flags, permanentFlags: string arrays\n - customKeywords: the mailbox's non-system keywords, usable as the\n `keywords` / `unKeywords` input of imap_search_emails\n ```\n\n- **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.\n ```\n Parameters:\n - accountId: Account ID\n - folder: Full folder path to create (e.g. \"Archives/2026/2026-05\" or \"INBOX.Archive\")\n ```\n\n- **imap_get_unread_count**: Count unread emails\n ```\n Parameters:\n - accountId: Account ID\n - folders: Specific folders (optional)\n ```\n\n## Security\n\n- Credentials are encrypted using AES-256-CBC encryption\n- Encryption keys are stored separately in `~/.imap-mcp/.key`\n- Account configurations are stored in `~/.imap-mcp/accounts.json`\n- The store directory, `.key`, and `accounts.json` are written owner-only\n (`0700`/`0600`) so other local users cannot read the key or the credentials\n- The web setup wizard's HTTP API never returns stored passwords to the browser\n- Downloaded attachments are confined to the downloads directory; sender-supplied\n filenames cannot write outside it\n- Never commit or share your encryption key or account configurations\n\n## Development\n\n### Running in Development Mode\n\n```bash\nnpm run dev\n```\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Project Structure\n\n```\nsrc/\nβββ index.ts # MCP server entry point\nβββ services/\nβ βββ imap-service.ts # IMAP connection management\nβ βββ smtp-service.ts # SMTP service for sending emails\nβ βββ account-manager.ts # Account configuration\nβββ tools/\nβ βββ index.ts # Tool registration\nβ βββ account-tools.ts # Account management tools\nβ βββ email-tools.ts # Email operation tools (including send/reply/forward)\nβ βββ folder-tools.ts # Folder operation tools\nβββ types/\n βββ index.ts # TypeScript type definitions\n```\n\n## Example Usage in Claude\n\n1. **Add an account:**\n \"Add my Gmail account with username john@gmail.com\"\n\n2. **Check new emails:**\n \"Show me the latest 5 emails from my Gmail account\"\n\n3. **Search emails:**\n \"Search for emails from boss@company.com in the last week\"\n\n4. **Send an email:**\n \"Send an email to client@example.com with subject 'Project Update'\"\n\n5. **Reply to emails:**\n \"Reply to the latest email from my boss\"\n\n6. **Forward emails:**\n \"Forward the email with subject 'Meeting Notes' to team@company.com\"\n\n7. **Move an email:**\n \"Move the invoice email from INBOX to my Taxes folder\"\n\n8. **Manage folders:**\n \"List all folders in my email account and show unread counts\"\n\n## Troubleshooting\n\n### Connection Issues\n\n- Ensure your IMAP server settings are correct\n- Check if your email provider requires app-specific passwords\n- Verify that IMAP is enabled in your email account settings\n- For sending emails, ensure your account has SMTP access enabled\n\n### Recipients arriving as `[\"a@x.com\",\"b@y.com\"]`\n\n`to`, `cc`, `bcc`, `references` and `uid` accept either a single value or an\narray. In JSON Schema that is an `anyOf`, and some MCP clients drop the `anyOf`\nbefore showing the schema to the model β the field then looks untyped or\nstring-typed, and the client serializes the model's array into a string. The\nserver used to pass that string straight to nodemailer, which folded the\nliteral `[` and `]` into the first and last address, so every recipient was\nrejected by the receiving mail server (issue #127).\n\nThe server now detects a stringified array and restores it, both when\nvalidating tool input and again before composing the message, and logs a\nwarning to stderr naming the field. Nothing needs to change on your side. If\nyou want to bypass the client behavior entirely, pass recipients as one\ncomma-separated string: `\"Alice , Bob \"`.\n\n### SMTP Configuration\n\nThe server automatically configures SMTP settings based on your IMAP provider. If you need custom SMTP settings, you can specify them when adding an account:\n\n```json\n{\n \"smtp\": {\n \"host\": \"smtp.example.com\",\n \"port\": 587,\n \"secure\": false\n }\n}\n```\n\n### Common IMAP Settings\n\n- **Gmail**: \n - Host: imap.gmail.com\n - Port: 993\n - Requires app-specific password\n\n- **Outlook/Hotmail**:\n - Host: outlook.office365.com\n - Port: 993\n\n- **Yahoo**:\n - Host: imap.mail.yahoo.com\n - Port: 993\n - Requires app-specific password\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bytes": 28179,
"sha": "2adc61edfdf6920e6511aa9cc501d59e439294688d681ff279e1561cc3875902",
"repo_slug": "nikolausm/imap-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_nikolausm_imap_mcp_server_76521960/readme"
}