{
  "markdown": "# Mailbridge MCP\n\nConnect your AI assistant to your email — read, search, send, reply, organise, draft, schedule, and manage attachments from iCloud or any IMAP account. Works with Claude, OpenAI Codex, Cursor, Windsurf, and any MCP-compatible client.\n\nCredentials are stored securely in your OS credential store (macOS Keychain, Windows Credential Manager, or Linux Keyring) — never in a file.\n\n---\n\n## Features\n\n### Reading & Search\n- **Read emails** — fetch inbox, any folder, with subject/sender/date\n- **Inbox digest** — smart summary with priority scoring, categories, and action suggestions\n- **Search** — find emails by keyword, sender, or subject\n- **Thread view** — see the full conversation thread for any email\n- **Contact history** — view all emails to/from a specific contact\n- **Unified inbox** — merge multiple folders into one date-sorted view\n- **Priority scoring** — every email is automatically scored 1–5 for urgency\n- **Auto-categorisation** — emails are tagged Finance, Travel, Calendar, Newsletter, and more\n\n### Sending & Drafts\n- **Send & reply** — compose new emails or reply with threading\n- **Send attachments** — attach local files or inline content to any outgoing email\n- **Smart drafts** — save emails locally for review before sending\n- **Email scheduling** — schedule emails to send at a future time\n- **Read receipts** — optionally request confirmation when a sent email is opened (recipient-dependent; see [Read Receipts](#read-receipts))\n\n### Organisation\n- **Bulk actions** — mark, move, or delete multiple emails in one command\n- **Follow-up reminders** — tag an email \"remind me in 3 days\" and it surfaces in your next digest\n- **Unsubscribe** — auto-unsubscribe from mailing lists via List-Unsubscribe headers\n- **Email rules** — define local rules to flag, categorise, or prioritise emails automatically\n- **Move, delete, mark** — standard inbox management tools\n\n### Attachments & Content\n- **Read attachments** — PDF, DOCX, TXT, JPG, PNG, MP3, MP4 and more\n- **Attachment safety** — every attachment is scanned before download; dangerous file types are blocked\n- **Export email** — export any email as clean Markdown\n- **Calendar extraction** — pull event details (dates, times, locations) from emails and .ics files\n\n### Accounts\n- **Multiple accounts** — connect and switch between accounts\n- **Secure credentials** — passwords stored in OS keychain, never in plain text\n\n---\n\n## Install\n\n### Claude Cowork\n\n1. Go to **Customize → Connectors → Browse Plugins → \"+\" sign**\n2. Add marketplace source: `https://github.com/Creativestefan/mailbridge-mcp`\n3. Start a new chat — and enter `Open Mailbridge setup` to open the setup portal and connect your email account\n4. For **iCloud emails** you will need to create an [App specfic password](https://appleid.apple.com/) to access your email securely. Using your real password will fail to authenicate. \n5. To reopen setup at any time: **\"open Mailbridge setup\"**\n\n**To update later:** Customize → Connectors → Browse Plugins → (...) button and Click Check for update\n\n---\n\n### OpenAI Codex\n\n1. Add the Mailbridge marketplace:\n\n```bash\ncodex plugin marketplace add Creativestefan/mailbridge-mcp --ref main\n```\n\n2. Install the plugin:\n\n```bash\ncodex plugin add mailbridge@mailbridge\n```\n\n3. Start a new Codex thread and test:\n\n```\nUse Mailbridge to check my email connection.\n```\n\n4. If no account is connected yet:\n\n```\nType \"Open Mailbridge setup\" and send.\n```\n\nThe setup portal saves credentials directly to your OS credential store (macOS Keychain, Windows Credential Manager, or Linux Keyring).\n\n**To update later:**\n\n```bash\ncodex plugin marketplace upgrade\ncodex plugin add mailbridge@mailbridge\n```\n\n---\n\n### Cursor\n\n1. Open **Cursor Settings → Tools & MCP**\n2. Click **Add MCP Server** and paste:\n\n```json\n{\n  \"mcpServers\": {\n    \"mailbridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mailbridge-mcp@latest\"]\n    }\n  }\n}\n```\n\n3. Fully quit and reopen Cursor (MCP servers only load at startup)\n4. Start a new chat and test:\n\n```\nUse Mailbridge to check my email connection.\n```\n\nIf no account is connected yet, the setup portal opens automatically — or ask: **\"open email setup\"**.\n\n**To update later:** bump the version tag in your config to `mailbridge-mcp@latest` — it always pulls the newest release.\n\n---\n\n### Via npm (any MCP client)\n\nAdd to your MCP client config (e.g. `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mailbridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"mailbridge-mcp\"]\n    }\n  }\n}\n```\n\nOn first start, if no account is configured, the setup portal opens automatically in your browser. Fill in your email details — credentials are saved directly to your OS credential store and the portal closes. You only need to do this once.\n\nTo reopen setup at any time, ask your assistant: **\"open email setup\"**\n\n---\n\n## Setup\n\nOn first install, a browser form opens automatically to connect your email account. Credentials go directly into your OS credential store on submit — nothing is written to a file.\n\nTo reopen setup at any time, just ask your assistant: **\"open email setup\"**.\n\n### iCloud\n\nYou must use an [App-Specific Password](https://account.apple.com) — your main Apple ID password will not work.\n\nGo to **account.apple.com → Sign-In & Security → App-Specific Passwords → +**, name it \"Mailbridge\", and use the generated password.\n\n### Custom IMAP account\n\nUse your full email address and password. The mail server is usually `mail.yourdomain.com` — check your email provider's settings if unsure.\n\n---\n\n## Tools\n\n### Reading\n\n| Tool | Description |\n|------|-------------|\n| `check_connection` | Test connection and show inbox stats |\n| `read_emails` | Fetch emails from any folder (includes priority + category) |\n| `get_email_body` | Get full body of an email by UID |\n| `get_emails_with_preview` | Fetch emails with body snippets — used for inbox summaries |\n| `search_emails` | Search by keyword, sender, or subject |\n| `list_folders` | List all mailbox folders |\n| `get_thread` | Fetch the full conversation thread for an email |\n| `get_contact_history` | All emails to/from a specific contact |\n| `unified_inbox` | Merge multiple folders into one sorted view |\n| `export_email` | Export an email as clean Markdown |\n| `extract_calendar_events` | Extract event details and parse .ics attachments |\n\n### Attachments\n\n| Tool | Description |\n|------|-------------|\n| `get_attachments` | List attachments with safety scan — no download |\n| `read_attachment` | Download and read an attachment after user approves |\n\n### Sending & Drafts\n\n| Tool | Description |\n|------|-------------|\n| `send_email` | Compose and send a new email (optional file attachments) |\n| `reply_to_email` | Reply to an existing email (optional file attachments) |\n| `save_draft` | Save an email as a local draft |\n| `list_drafts` | List saved drafts |\n| `send_draft` | Send a saved draft by ID |\n| `delete_draft` | Discard a saved draft |\n| `schedule_email` | Schedule an email for future delivery |\n| `list_scheduled` | List pending scheduled emails |\n| `cancel_scheduled` | Cancel a scheduled email |\n| `check_email_opens` | Scan the inbox for read-receipt confirmations and report opens |\n| `list_tracked_emails` | Show tracked emails and their open status (no inbox scan) |\n\n### Organisation\n\n| Tool | Description |\n|------|-------------|\n| `mark_as_read` | Mark email as read |\n| `mark_as_unread` | Mark email as unread |\n| `move_email` | Move email to another folder |\n| `delete_email` | Move email to Trash |\n| `bulk_mark_read` | Mark multiple emails as read |\n| `bulk_mark_unread` | Mark multiple emails as unread |\n| `bulk_move` | Move multiple emails to a folder |\n| `bulk_delete` | Move multiple emails to Trash |\n| `set_reminder` | Set a follow-up reminder on an email |\n| `list_reminders` | View active reminders (overdue ones flagged) |\n| `complete_reminder` | Mark a reminder as done |\n| `unsubscribe_email` | Auto-unsubscribe via List-Unsubscribe header |\n\n### Rules\n\n| Tool | Description |\n|------|-------------|\n| `add_rule` | Add a local rule to flag, categorise, or prioritise emails |\n| `list_rules` | List all configured rules |\n| `remove_rule` | Remove a rule by name |\n| `apply_rules` | Dry-run rules against a set of emails |\n\n### Accounts\n\n| Tool | Description |\n|------|-------------|\n| `list_accounts` | Show all connected accounts |\n| `switch_account` | Switch active account |\n| `add_account` | Add a new account via chat |\n| `remove_account` | Remove an account (defaults to active) |\n| `remove_all_accounts` | Disconnect and remove all accounts |\n| `open_setup` | Open the setup portal to connect or add an account |\n\n---\n\n## Inbox Summary\n\nAsk your assistant **\"catch me up\"** or **\"what did I miss?\"** for a structured digest.\n\nEvery email now carries automatic **priority scoring** (1–5) and **category tags** so the digest is sorted instantly:\n\n- 🔴 **Action Required** — priority 4–5 or keywords like \"urgent\", \"deadline\", \"reply needed\"\n- 💰 **Finance & Billing** — invoices, payments, subscription renewals\n- 📅 **Events & Calendar** — meeting invites, travel confirmations, RSVPs\n- 📦 **Updates & FYI** — newsletters, notifications, low-priority\n\n**Follow-up reminders** due today or overdue are surfaced at the top of every digest.\n\nThe digest closes with a **suggested actions** block — specific next steps like \"unsubscribe from X\", \"set a reminder on Y\", or \"bulk archive the 8 newsletters\".\n\n---\n\n## Drafts & Scheduling\n\nSave any email as a draft before sending:\n> \"Draft a reply to this email — I'll review it first\"\n\nSchedule an email for later:\n> \"Send this to john@example.com tomorrow at 9am\"\n\nScheduled emails fire automatically on the next session start after the scheduled time.\n\n---\n\n## Read Receipts\n\nAsk Mailbridge to track when a sent email is opened:\n\n> \"Send this to john@example.com and let me know when he opens it\"\n\nThis sets `request_receipt: true`, which adds standard **read-receipt headers (RFC 8098 / MDN)** to the message. Later:\n\n> \"Did John open my email?\"\n\nruns `check_email_opens`, which scans your inbox for the recipient's confirmation and reports who opened it and when.\n\n**How it actually works — and its limits:**\n\n- Mailbridge uses **read-receipt headers, not tracking pixels**. Nothing phones home to any server; the recipient's mail app asks *them* to confirm, and the confirmation comes back as a normal email that Mailbridge reads locally.\n- A receipt only arrives if the recipient's client **supports** read receipts **and** the recipient **agrees** to send one. Apple Mail and Thunderbird prompt for this; **Gmail's web app ignores it**.\n- **No receipt does not mean the email was unread.** An \"awaiting\" status simply means no confirmation has come back — it is not proof of anything.\n- This is intentionally the privacy-respecting approach: no invisible pixels, no third-party trackers, no data leaving your device.\n\n---\n\n## Email Rules\n\nDefine local rules that apply automatically during inbox summaries:\n\n> \"Flag all emails from boss@company.com as urgent\"\n> \"Categorise anything from billing@stripe.com as Finance\"\n> \"Set priority 5 on emails with 'invoice due' in the subject\"\n\nRules are stored locally — they work without any server-side filtering.\n\n---\n\n## Attachments\n\nMailbridge scans every attachment before downloading:\n\n| Safety | Meaning |\n|--------|---------|\n| ✅ Safe | Known safe file type, extension matches MIME type |\n| ⚠️ Warning | Unrecognised extension or MIME mismatch — will not auto-download |\n| 🚫 Blocked | Executable or script file — refused outright (.exe, .bat, .ps1, .sh, .jar, etc.) |\n\n**Supported file types:**\n\n| Type | What happens |\n|------|-------------|\n| PDF | Text extracted and displayed |\n| DOCX | Text extracted and displayed |\n| TXT, CSV, MD | Displayed as plain text |\n| JPG, PNG, GIF, WebP | Displayed inline — the AI can see and describe the image |\n| MP3, MP4, WAV, M4A | Saved to temp path — pass to a transcription plugin |\n\n---\n\n## Supported Providers\n\n| Provider | IMAP | SMTP |\n|----------|------|------|\n| iCloud | `imap.mail.me.com:993` | `smtp.mail.me.com:587` |\n| Custom IMAP | Your mail server | Your mail server |\n\n---\n\n## Security\n\n- Passwords are stored exclusively in the OS credential store — never written to any file\n- The setup portal is a one-time browser form — it starts, collects your credentials, saves them to your OS keychain, then shuts down automatically\n- All IMAP and SMTP connections use SSL/TLS\n- Attachments are scanned before download — executables and scripts are always blocked\n- No data is sent to any Mailbridge server — everything runs locally on your device\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n## Legal\n\n- [Privacy Policy](PRIVACY.md)\n- [Terms of Use](TERMS.md)\n",
  "bytes": 12779,
  "sha": "4b50c8f402ff88bc0d72fa575d0f36c625b80041cb906f6964509880b6af3420",
  "repo_slug": "creativestefan/mailbridge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_creativestefan_mailbridge_03357267/readme"
}