{
  "markdown": "# @aiwerk/mcp-server-imap\n\n[![npm version](https://img.shields.io/npm/v/@aiwerk/mcp-server-imap)](https://www.npmjs.com/package/@aiwerk/mcp-server-imap)\n[![npm downloads](https://img.shields.io/npm/dm/@aiwerk/mcp-server-imap)](https://www.npmjs.com/package/@aiwerk/mcp-server-imap)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**IMAP/SMTP MCP server that works with any email provider.** Set host, user, pass — done.\n\nUnlike Gmail-only or Outlook-only MCP servers, this one speaks standard IMAP/SMTP — so it works with **every** email provider out of the box.\n\n## Why this server?\n\nMost email MCP servers only work with one provider (Gmail, Outlook). This one works with **any** provider that supports IMAP:\n\n- Gmail, Outlook, Yahoo — yes\n- Fastmail, ProtonMail Bridge, Zoho — yes\n- Self-hosted (Dovecot, Postfix, hMailServer) — yes\n- Corporate/hosted (Hostpoint, Infomaniak, OVH) — yes\n\nOne server, every mailbox.\n\n## Highlights\n\n- **Universal** — standard IMAP/SMTP, works everywhere\n- **Simple setup** — just `IMAP_HOST`, `IMAP_USER`, `IMAP_PASS` and you're connected\n- **Safety first** — email sending is **disabled by default** (`SMTP_SEND_ENABLED=false`). Your AI agent can read emails but can't send anything until you explicitly opt in\n- **Lazy credentials** — the server starts and exposes its tool list without requiring credentials. Auth is only needed when a tool is actually called\n- **Real MIME parsing** — handles multipart, HTML/text, attachments, reply threading\n\n## AIWerk hosted service — `email_send` and `email_reply` are local-only\n\nIf you use this server through the AIWerk hosted service at [aiwerkmcp.com](https://aiwerkmcp.com), the two outgoing-mail tools are not exposed:\n\n- ❌ `email_send`\n- ❌ `email_reply`\n\nThe other 8 read-side tools (`email_list`, `email_read`, `email_search`, `email_folders`, `email_flag`, `email_move`, `email_delete`, `email_attachment`) work normally on the hosted service.\n\n**Why?** The hosted service shares an IP across all users. If outgoing mail went out from that shared IP, the IP would appear in every recipient's `Received:` headers — one bad actor could damage deliverability for every user. There is no shared-IP architecture where arbitrary user sends works safely.\n\n**How to send mail then?** Run the server locally, where outgoing mail goes from your own IP and your own provider reputation. Three paths:\n\n1. **Ad-hoc one-email CLI** — see the next section. Zero config, one-shot.\n2. **Direct stdio MCP server** in your client (Cursor, Claude Desktop, OpenClaw) — point your client config at `npx -y @aiwerk/mcp-server-imap` with your `IMAP_*` and `SMTP_*` env vars including `SMTP_SEND_ENABLED=true`.\n3. **Local `@aiwerk/mcp-bridge`** — `npx -y @aiwerk/mcp-bridge install imap-email --catalog aiwerkmcp.com`, then point your client at the local bridge endpoint.\n\nIn all three cases the mail goes from your home / office IP, not from the hosted service.\n\n## Ad-hoc one-email CLI\n\n> **Note:** On the AIWerk hosted service, the `email_send` and `email_reply` MCP tools are not exposed (the service shares an IP across all users, so allowing arbitrary sends would risk every user's deliverability). Use any of the three paths below to send email locally.\n\nNeed to send a single email from the command line — for example, to deliver a draft your AI agent composed? Use `aiwerk-send-email`:\n\n```bash\nSMTP_HOST=smtp.gmail.com \\\nSMTP_PORT=587 \\\nSMTP_USER=me@gmail.com \\\nSMTP_PASS='app-password' \\\nSMTP_FROM='Me <me@gmail.com>' \\\nnpx -y @aiwerk/mcp-server-imap aiwerk-send-email \\\n  --to \"alice@example.com\" \\\n  --subject \"Re: invoice\" \\\n  --body \"Got it, will pay Monday.\"\n```\n\nOn success, exits 0 and prints JSON: `{\"ok\":true,\"messageId\":\"...\",\"envelope\":{...}}`\n\nOn failure, exits 1 with the error on stderr. Credentials are never printed.\n\n### All CLI arguments\n\n| Argument | Required | Description |\n|---|---|---|\n| `--to` | Yes | Recipient(s), comma-separated |\n| `--subject` | Yes | Subject line |\n| `--body` | One of body/html | Plain-text body |\n| `--html` | One of body/html | HTML body (both → multipart) |\n| `--in-reply-to` | No | `Message-ID` of original message (thread preservation) |\n| `--references` | No | Space-separated reference IDs |\n| `--cc` | No | CC recipients, comma-separated |\n| `--bcc` | No | BCC recipients, comma-separated |\n\n### CLI environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `SMTP_HOST` | Yes | — | SMTP server hostname |\n| `SMTP_PORT` | Yes | — | `587` for STARTTLS, `465` for implicit TLS |\n| `SMTP_USER` | Yes | — | SMTP username / email address |\n| `SMTP_PASS` | Yes | — | Password or app-specific password |\n| `SMTP_FROM` | Yes | — | Sender address (`Name <email>` or plain email) |\n| `SMTP_TLS` | No | `false` | `true` for implicit TLS (port 465); `false` for STARTTLS (port 587) |\n\n---\n\n## Install\n\nThree ways to get email tools — pick the one that fits.\n\n**1. Quick (single email)** — `aiwerk-send-email` CLI above: no MCP client needed, one command sends one email.\n\n**2. Direct stdio MCP server** — all 10 email tools exposed to your AI agent:\n\n```bash\nnpx -y @aiwerk/mcp-server-imap\n```\n\n**3. Local bridge with catalog UX** — install via the AIWerk catalog for a guided setup:\n\n```bash\nnpx -y @aiwerk/mcp-bridge install imap-email --catalog bridge.aiwerk.ch\n```\n\n### Option 1 — Hosted (zero setup)\n\nNo local runtime, no env vars on your machine — credentials are AES-256-GCM encrypted server-side via HashiCorp Vault.\n\n1. Sign up at **[aiwerkmcp.com](https://aiwerkmcp.com)**.\n2. Install **IMAP Email** from the catalog and paste your IMAP/SMTP credentials.\n3. Point your MCP client (Claude.ai, Cursor, Hermes, …) at your hosted endpoint:\n   ```\n   https://bridge.aiwerk.ch/u/<your-user-id>/mcp\n   ```\n   with your Bearer token.\n\nAll 10 tools appear immediately. Install other AIWerk recipes from the same bridge.\n\n### Option 2 — Self-hosted (npx)\n\nRun directly — you manage the credentials:\n\n```bash\nIMAP_HOST=\"imap.example.com\" \\\nIMAP_USER=\"user@example.com\" \\\nIMAP_PASS=\"app-password\" \\\nSMTP_HOST=\"smtp.example.com\" \\\nnpx @aiwerk/mcp-server-imap\n```\n\nThe server starts immediately and responds to `tools/list` even without credentials — they're only required when a tool is actually called (lazy credentials).\n\n## Tools (10)\n\n| Tool | Purpose |\n|---|---|\n| `email_list` | List emails from a folder |\n| `email_read` | Read a single message with full body |\n| `email_search` | Search by from/to/subject/date/unread |\n| `email_folders` | List all folders with message counts |\n| `email_move` | Move messages between folders |\n| `email_flag` | Set read/star/flag status |\n| `email_delete` | Move messages to Trash |\n| `email_send` | Send a new email (requires opt-in) |\n| `email_reply` | Reply to a message (requires opt-in) |\n| `email_attachment` | List or download attachments |\n\n## Configuration\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"email\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aiwerk/mcp-server-imap\"],\n      \"env\": {\n        \"IMAP_HOST\": \"imap.example.com\",\n        \"IMAP_USER\": \"you@example.com\",\n        \"IMAP_PASS\": \"your-app-password\",\n        \"SMTP_HOST\": \"smtp.example.com\"\n      }\n    }\n  }\n}\n```\n\n### Cursor / Windsurf / VS Code\n\nSame config format in the respective MCP settings.\n\n### AIWerk hosted service\n\nIf you want zero-setup, install via [aiwerkmcp.com](https://aiwerkmcp.com) — see [Option 1](#option-1--hosted-zero-setup) above.\n\n## Environment variables\n\n### IMAP (required)\n\n| Variable | Default | Description |\n|---|---|---|\n| `IMAP_HOST` | — | IMAP server hostname |\n| `IMAP_USER` | — | Email address or username |\n| `IMAP_PASS` | — | Password or app-specific password |\n| `IMAP_PORT` | `993` | IMAP port |\n| `IMAP_TLS` | `true` | Use TLS |\n| `IMAP_TIMEOUT` | `30000` | Connection timeout (ms) |\n\n### SMTP (optional, for sending)\n\n| Variable | Default | Description |\n|---|---|---|\n| `SMTP_HOST` | `${IMAP_HOST}` | SMTP server hostname |\n| `SMTP_PORT` | `465` | SMTP port |\n| `SMTP_USER` | `${IMAP_USER}` | SMTP username |\n| `SMTP_PASS` | `${IMAP_PASS}` | SMTP password |\n| `SMTP_TLS` | `true` | Use TLS |\n| `SMTP_FROM` | `${IMAP_USER}` | Sender address |\n| `SMTP_SEND_ENABLED` | `false` | **Must be `true` to enable sending** |\n\n### Debug\n\n| Variable | Default | Description |\n|---|---|---|\n| `IMAP_DEBUG` | `false` | Verbose IMAP protocol logging |\n\n## Security\n\n- Email sending is **disabled by default** — set `SMTP_SEND_ENABLED=true` to enable\n- Credentials are loaded lazily (only when a tool is called, not at startup)\n- No credentials are logged\n- Keep credentials in `.env` or a secret manager — never commit them to git\n\n## Supported providers\n\nTested with: Hostpoint, Gmail (app password), Outlook/Microsoft 365, Yahoo Mail, Fastmail, Dovecot, Postfix.\n\nWorks with any standards-compliant IMAP/SMTP server.\n\n## Build from source\n\n```bash\ngit clone https://github.com/AIWerk/mcp-server-imap\ncd mcp-server-imap\nnpm install\nnpm run build\nnode dist/server.js\n```\n\n## Contributing\n\nIssues and PRs are welcome! Please open an issue first for larger changes.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n## About AIWerk MCP\n\nPart of the **[AIWerk MCP platform](https://aiwerkmcp.com)** — curated, signed MCP recipes served either as npm packages for self-hosting or through our multi-tenant hosted service at [aiwerkmcp.com](https://aiwerkmcp.com).\n\nOther AIWerk MCP servers:\n\n- [@aiwerk/mcp-server-cal](https://github.com/AIWerk/mcp-server-cal) — Cal.com scheduling\n- [@aiwerk/mcp-server-wise](https://github.com/AIWerk/mcp-server-wise) — Wise (TransferWise) Personal API, read-only\n- [@aiwerk/mcp-server-clawhub](https://github.com/AIWerk/mcp-server-clawhub) — ClawHub skill catalog\n\nBrowse the full catalog (20+ recipes including GitHub, Linear, Notion, Stripe, …) at [aiwerkmcp.com](https://aiwerkmcp.com).\n\n## License\n\nMIT — [AIWerk](https://aiwerk.ch)\n",
  "bytes": 9965,
  "sha": "8624a51573e71a322416232c5b70b68193ecda28a78df41b861ca08fbc9d6148",
  "repo_slug": "aiwerk/mcp-server-imap",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiwerk_mcp_server_imap_44aa2638/readme"
}