Mail MCP Bridge

🚀 Mail MCP Bridge

Connect macOS Mail to AI through Model Context Protocol (MCP). This project enables AI assistants to directly access and analyze your macOS Mail emails, streamlining the process and saving you time.

🚀 Quick Start

Prerequisites

• macOS 12.0+ (with Mail app)
• Python 3.9+
• MCP-compatible AI assistant (e.g., Claude Desktop)

Installation

# Clone the repository
git clone https://github.com/fatbobman/mail-mcp-bridge.git
cd mail-mcp-bridge

# Install MCP dependencies
pip3 install mcp

Configure Claude Desktop

1. Find config location:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

2. Edit config (create if doesn't exist):

   {
     "mcpServers": {
       "mail": {
         "command": "python3",
         "args": [
           "/path/to/mail-mcp-bridge/src/mail_mcp_server.py"
         ]
       }
     }
   }
   

   Important: Replace /path/to/mail-mcp-bridge with your actual project path. Optional: Configure attachment temp directory (defaults to /tmp/mail-mcp-attachments):

   {
     "mcpServers": {
       "mail": {
         "command": "python3",
         "args": [
           "/path/to/mail-mcp-bridge/src/mail_mcp_server.py"
         ],
         "env": {
           "MAIL_ATTACHMENT_PATH": "/tmp"
         }
       }
     }
   }
   

3. Restart Claude Desktop (quit completely, then reopen)

Install Claude Code Plugins (Optional but Recommended)

Mail MCP includes ready-to-use Claude Code plugins that provide intelligent email analysis capabilities: What you get:

• 🎯 Smart Attachment Analysis - Automatically detects important attachments (invoices, contracts, tax docs)
• 🧵 Thread Tracking - Tracks document evolution across email conversations
• 🚀 3 Analysis Modes - Quick/Interactive/Auto modes to optimize token usage
• 📋 Action Item Extraction - Finds deadlines and tasks in emails

Install:

# 1. Add the Mail MCP plugin marketplace
/plugin marketplace add /path/to/mail-mcp-bridge/plugins

# 2. Install the attachment analyzer
/plugin install mail-attachment-analyzer@mail-mcp

# 3. Restart Claude Code

Replace /path/to/mail-mcp-bridge with your actual installation path.

Usage: After installation, the plugin works automatically:

You: Analyze this email <message-id@example.com>
AI: [Automatically detects attachments and analyzes intelligently]

Or use manual commands:

/mail-mcp:analyze-attachment

📖 → Plugin Documentation

Setup Mail Quick Action

Add a "Copy Message-ID" button to Mail app: Step-by-Step:

1. Open Automator (⌘ + Space, type "Automator")
2. Create new Quick Action:
   • File → New (⌘ + N)
   • Select "Quick Action"
   • Workflow receives current: no input
   • in: Mail.app
3. Add Run Shell Script action:
   • Search "Run Shell Script" in left panel
   • Drag to workflow area
   • Shell: /bin/bash
4. Copy script content:

   cat automator_script.sh
   

   Paste entire output into Automator script area
5. Save as "Copy Message-ID"
6. (Optional) Assign keyboard shortcut:
   • System Settings → Keyboard → Keyboard Shortcuts
   • Services → Mail → "Copy Message-ID"
   • Add shortcut (e.g., ⌘ + ⇧ + C)

Automator Setup Example:

Test It:

1. Open Mail app
2. Select any email
3. Press your keyboard shortcut (if configured)
4. You should hear a sound confirming Message-ID copied

✨ Features

• 📧 Direct Access - AI reads your emails through MCP protocol
• 🧵 Thread Support - Retrieve entire conversations with one Message-ID
• 📎 Attachment Extraction - Extract email attachments for AI analysis (PDFs, documents, images)
• 🎨 Claude Code Plugins - Pre-built commands and skills for intelligent email analysis
• ⚡ Fast - Millisecond-level query response
• 🎯 Clean Text - Optimized text extraction for AI (excludes HTML, embedded images)
• 🔒 Privacy First - Runs locally, emails never leave your Mac

💻 Usage Examples

Basic Usage

1. Select email in Mail
2. Press your keyboard shortcut (e.g., ⌘⇧C)
3. Paste Message-ID to AI

Example Conversations

Read Single Email:

You: Please analyze this email: <message-id@example.com>

AI: I'll read that email for you...
[AI reads and analyzes the email content]

Read Email Thread:

You: What's the full conversation for <message-id@example.com>?

AI: I'll retrieve the entire thread...
[AI shows all emails in the conversation]

Real-World Use Case:

You: Please summarize all communication with our business partner,
including their requirements, promised timelines, and action items.

AI: I'll read the relevant email threads and extract key information...
[AI analyzes email content, organizes project progress, commitments, and action items]

Extract Email Attachments:

You: Extract and analyze the PDF invoice from this email: <message-id@example.com>

AI: I can see this email has an invoice.pdf attachment (1.2MB). Let me extract it...
[AI extracts attachment and analyzes the content]

📚 Documentation

• TOOLS.md - Complete API reference for all MCP tools
• ARCHITECTURE.md - Technical architecture and database structure
• README_zh.md - Chinese documentation

🔧 Technical Details

┌─────────────┐
│  Mail App   │ Select email → Copy Message-ID (⌘⇧C)
└──────┬──────┘
       │
       ↓ Message-ID
┌─────────────┐
│MCP Server   │ 1. Query Mail SQLite database
│             │ 2. Locate .emlx file by ROWID
│             │ 3. Parse email content
│             │ 4. Extract plain text
└──────┬──────┘
       │
       ↓ Structured Data
┌─────────────┐
│ AI Assistant│ Analyze email content
└─────────────┘

🔧 → Technical Architecture

🛠️ MCP Tools

📖 → Detailed API Documentation

🐛 Troubleshooting

MCP server not found

Solution:

# Verify the path in claude_desktop_config.json
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart Claude Desktop (quit completely, then reopen)

Email not found

Possible causes:

1. Message-ID format incorrect (must include < >)
2. Email deleted from Mail
3. Email in different Mail account database

Permission denied

Solution:

# Make scripts executable
chmod +x *.py *.sh

🔒 Privacy & Security

• ✅ Local Processing: All operations run locally on your Mac
• ✅ No External Servers: No data sent to external servers
• ✅ No Telemetry: No analytics or tracking
• ✅ Read-Only: Only reads email data, never modifies

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

🌟 Acknowledgments

• Built for the MCP (Model Context Protocol) ecosystem
• Inspired by the need to bridge email and AI
• Tested with Claude Desktop on macOS 26 (Tahoe)

📮 Contact

• Issues: https://github.com/fatbobman/mail-mcp-bridge/issues
• Author: Fatbobman (Xu Yang)

☕ Buy Me a Coffee

If you find this project helpful, consider buying me a coffee!

Made with ❤️ for the AI community