{"id":50557655,"url":"https://github.com/nikolausm/imap-mcp-server","last_synced_at":"2026-06-27T14:00:28.610Z","repository":{"id":305012876,"uuid":"1021605888","full_name":"nikolausm/imap-mcp-server","owner":"nikolausm","description":"A powerful Model Context Protocol (MCP) server for IMAP email integration with Claude","archived":false,"fork":false,"pushed_at":"2026-06-25T09:47:48.000Z","size":341,"stargazers_count":47,"open_issues_count":10,"forks_count":19,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T11:18:12.492Z","etag":null,"topics":["ai","claude","email","imap","llm","mcp","mcp-server","model-context-protocol","smtp","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikolausm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-17T16:48:55.000Z","updated_at":"2026-06-25T09:46:58.000Z","dependencies_parsed_at":"2025-07-17T23:08:38.351Z","dependency_job_id":"7615bb99-11b1-441b-909e-7f4475105d6f","html_url":"https://github.com/nikolausm/imap-mcp-server","commit_stats":null,"previous_names":["nikolausm/imap-mcp-server"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/nikolausm/imap-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolausm%2Fimap-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolausm%2Fimap-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolausm%2Fimap-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolausm%2Fimap-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikolausm","download_url":"https://codeload.github.com/nikolausm/imap-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolausm%2Fimap-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34855826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","email","imap","llm","mcp","mcp-server","model-context-protocol","smtp","typescript"],"created_at":"2026-06-04T09:00:18.179Z","updated_at":"2026-06-27T14:00:28.594Z","avatar_url":"https://github.com/nikolausm.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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### 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\u003e \"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### 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\u00261)\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\u003e **Important:** Replace `/absolute/path/to/imap-mcp-server` with the actual path where you cloned the repository. For example:\n\u003e ```bash\n\u003e # macOS/Linux example:\n\u003e claude mcp add imap -- node /Users/yourname/imap-mcp-server/dist/index.js\n\u003e\n\u003e # Windows example:\n\u003e claude mcp add imap -- node C:\\Users\\yourname\\imap-mcp-server\\dist\\index.js\n\u003e ```\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\u003e **Tip:** If you want to remove the server later, run:\n\u003e ```bash\n\u003e claude mcp remove imap\n\u003e ```\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\u003e **Choosing an account.** For the email and folder tools, `accountId` is\n\u003e **optional** and backward-compatible. You may instead pass `accountName`, and\n\u003e if you only have a **single** account configured you can omit both — that\n\u003e account is used by default. With multiple accounts and no selector, the tool\n\u003e 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  ```\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  - limit: Max results (default: 50)\n  ```\n  \u003e With `searchAllFolders`, results include a `folder` field per message plus\n  \u003e `foldersSearched`, and any folder that failed to open is reported in\n  \u003e `foldersErrored` (so a 0-result answer is never silently incomplete).\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  ```\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\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\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  ```\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\n- **imap_send_email**: Send a new email\n  ```\n  Parameters:\n  - accountId: Account ID to send from\n  - to: Recipient email address(es)\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  ```\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  - attachments: Array of attachments (optional)\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  - 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\n- **imap_folder_status**: Get folder information\n  ```\n  Parameters:\n  - accountId: Account ID\n  - folder: Folder name\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- 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### 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolausm%2Fimap-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikolausm%2Fimap-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolausm%2Fimap-mcp-server/lists"}