Mailbridge MCP
Connect 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.
Credentials are stored securely in your OS credential store (macOS Keychain, Windows Credential Manager, or Linux Keyring) — never in a file.
Features
Reading & Search
- Read emails — fetch inbox, any folder, with subject/sender/date
- Inbox digest — smart summary with priority scoring, categories, and action suggestions
- Search — find emails by keyword, sender, or subject
- Thread view — see the full conversation thread for any email
- Contact history — view all emails to/from a specific contact
- Unified inbox — merge multiple folders into one date-sorted view
- Priority scoring — every email is automatically scored 1–5 for urgency
- Auto-categorisation — emails are tagged Finance, Travel, Calendar, Newsletter, and more
Sending & Drafts
- Send & reply — compose new emails or reply with threading
- Send attachments — attach local files or inline content to any outgoing email
- Smart drafts — save emails locally for review before sending
- Email scheduling — schedule emails to send at a future time
- Read receipts — optionally request confirmation when a sent email is opened (recipient-dependent; see Read Receipts)
Organisation
- Bulk actions — mark, move, or delete multiple emails in one command
- Follow-up reminders — tag an email "remind me in 3 days" and it surfaces in your next digest
- Unsubscribe — auto-unsubscribe from mailing lists via List-Unsubscribe headers
- Email rules — define local rules to flag, categorise, or prioritise emails automatically
- Move, delete, mark — standard inbox management tools
Attachments & Content
- Read attachments — PDF, DOCX, TXT, JPG, PNG, MP3, MP4 and more
- Attachment safety — every attachment is scanned before download; dangerous file types are blocked
- Export email — export any email as clean Markdown
- Calendar extraction — pull event details (dates, times, locations) from emails and .ics files
Accounts
- Multiple accounts — connect and switch between accounts
- Secure credentials — passwords stored in OS keychain, never in plain text
Install
Claude Cowork
- Go to Customize → Connectors → Browse Plugins → "+" sign
- Add marketplace source:
https://github.com/Creativestefan/mailbridge-mcp - Start a new chat — and enter
Open Mailbridge setupto open the setup portal and connect your email account - For iCloud emails you will need to create an App specfic password to access your email securely. Using your real password will fail to authenicate.
- To reopen setup at any time: "open Mailbridge setup"
To update later: Customize → Connectors → Browse Plugins → (...) button and Click Check for update
OpenAI Codex
- Add the Mailbridge marketplace:
codex plugin marketplace add Creativestefan/mailbridge-mcp --ref main
- Install the plugin:
codex plugin add mailbridge@mailbridge
- Start a new Codex thread and test:
Use Mailbridge to check my email connection.
- If no account is connected yet:
Type "Open Mailbridge setup" and send.
The setup portal saves credentials directly to your OS credential store (macOS Keychain, Windows Credential Manager, or Linux Keyring).
To update later:
codex plugin marketplace upgrade
codex plugin add mailbridge@mailbridge
Cursor
- Open Cursor Settings → Tools & MCP
- Click Add MCP Server and paste:
{
"mcpServers": {
"mailbridge": {
"command": "npx",
"args": ["-y", "mailbridge-mcp@latest"]
}
}
}
- Fully quit and reopen Cursor (MCP servers only load at startup)
- Start a new chat and test:
Use Mailbridge to check my email connection.
If no account is connected yet, the setup portal opens automatically — or ask: "open email setup".
To update later: bump the version tag in your config to mailbridge-mcp@latest — it always pulls the newest release.
Via npm (any MCP client)
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"mailbridge": {
"command": "npx",
"args": ["mailbridge-mcp"]
}
}
}
On 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.
To reopen setup at any time, ask your assistant: "open email setup"
Setup
On 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.
To reopen setup at any time, just ask your assistant: "open email setup".
iCloud
You must use an App-Specific Password — your main Apple ID password will not work.
Go to account.apple.com → Sign-In & Security → App-Specific Passwords → +, name it "Mailbridge", and use the generated password.
Custom IMAP account
Use your full email address and password. The mail server is usually mail.yourdomain.com — check your email provider's settings if unsure.
Tools
Reading
Attachments
Sending & Drafts
Organisation
Rules
Accounts
Inbox Summary
Ask your assistant "catch me up" or "what did I miss?" for a structured digest.
Every email now carries automatic priority scoring (1–5) and category tags so the digest is sorted instantly:
- 🔴 Action Required — priority 4–5 or keywords like "urgent", "deadline", "reply needed"
- 💰 Finance & Billing — invoices, payments, subscription renewals
- 📅 Events & Calendar — meeting invites, travel confirmations, RSVPs
- 📦 Updates & FYI — newsletters, notifications, low-priority
Follow-up reminders due today or overdue are surfaced at the top of every digest.
The 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".
Drafts & Scheduling
Save any email as a draft before sending:
"Draft a reply to this email — I'll review it first"
Schedule an email for later:
"Send this to [email protected] tomorrow at 9am"
Scheduled emails fire automatically on the next session start after the scheduled time.
Read Receipts
Ask Mailbridge to track when a sent email is opened:
"Send this to [email protected] and let me know when he opens it"
This sets request_receipt: true, which adds standard read-receipt headers (RFC 8098 / MDN) to the message. Later:
"Did John open my email?"
runs check_email_opens, which scans your inbox for the recipient's confirmation and reports who opened it and when.
How it actually works — and its limits:
- 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.
- 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.
- 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.
- This is intentionally the privacy-respecting approach: no invisible pixels, no third-party trackers, no data leaving your device.
Email Rules
Define local rules that apply automatically during inbox summaries:
"Flag all emails from [email protected] as urgent" "Categorise anything from [email protected] as Finance" "Set priority 5 on emails with 'invoice due' in the subject"
Rules are stored locally — they work without any server-side filtering.
Attachments
Mailbridge scans every attachment before downloading:
Supported file types:
Supported Providers
Security
- Passwords are stored exclusively in the OS credential store — never written to any file
- The setup portal is a one-time browser form — it starts, collects your credentials, saves them to your OS keychain, then shuts down automatically
- All IMAP and SMTP connections use SSL/TLS
- Attachments are scanned before download — executables and scripts are always blocked
- No data is sent to any Mailbridge server — everything runs locally on your device
License
MIT — see LICENSE