https://github.com/fatbobman/mail-mcp-bridge
Connect macOS Mail to AI through Model Context Protocol
https://github.com/fatbobman/mail-mcp-bridge
ai ai-assistant automation claude email email-client email-tools integration llm macos macos-mail mcp mcp-server openai productivity python
Last synced: 3 months ago
JSON representation
Connect macOS Mail to AI through Model Context Protocol
- Host: GitHub
- URL: https://github.com/fatbobman/mail-mcp-bridge
- Owner: fatbobman
- License: mit
- Created: 2025-12-26T13:40:02.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2025-12-27T04:01:20.000Z (6 months ago)
- Last Synced: 2025-12-28T01:44:13.660Z (6 months ago)
- Topics: ai, ai-assistant, automation, claude, email, email-client, email-tools, integration, llm, macos, macos-mail, mcp, mcp-server, openai, productivity, python
- Language: Python
- Homepage: https://fatbobman.com
- Size: 1.02 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Mail MCP Bridge
> Connect macOS Mail to AI through Model Context Protocol (MCP)
**Mail MCP Bridge** enables AI assistants (like Claude, ChatGPT) to directly access and analyze your macOS Mail emails. Simply copy a Message-ID from Mail and paste it to AI โ no manual email exporting needed.
**Demo: See it in action** (Click to watch)
*Shows: Copy Message-ID from Mail โ AI analyzes email content*
[๐จ๐ณ ไธญๆ็](README_zh.md)
## ๐ฏ What & Why
**The Problem**: Much of real-world communication happens through email โ project collaborations, client communications, business negotiations, technical support. Manually exporting emails for AI analysis is tedious and inefficient.
**The Solution**: Mail MCP Bridge lets AI directly read your emails through a simple workflow:
- Copy Message-ID from Mail (one keyboard shortcut)
- Paste to AI
- AI analyzes email content instantly
**Use Cases**:
- ๐ Track project progress via email threads
- ๐ผ Extract key information from business communications
- ๐ Summarize long email conversations
- ๐ Extract structured data (requirements, feedback, commitments)
- ๐ค Review conversation history
- ๐ Analyze email attachments (invoices, reports, documents)
## โจ 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
## ๐ Quick Start
### Prerequisites
- macOS 12.0+ (with Mail app)
- Python 3.9+
- MCP-compatible AI assistant (e.g., Claude Desktop)
### Installation
```bash
# 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**:
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```
2. **Edit config** (create if doesn't exist):
```json
{
"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`):
```json
{
"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**:
```bash
# 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
AI: [Automatically detects attachments and analyzes intelligently]
```
Or use manual commands:
```
/mail-mcp:analyze-attachment
```
๐ **[โ Plugin Documentation](plugins/README.md)**
### 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:
```bash
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
## ๐ Usage
### Basic Workflow
```
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:
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 ?
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**:
```text
You: Extract and analyze the PDF invoice from this email:
AI: I can see this email has an invoice.pdf attachment (1.2MB). Let me extract it...
[AI extracts attachment and analyzes the content]
```
## ๐ ๏ธ MCP Tools
| Tool | Description |
|------|-------------|
| `get_email_path` | Get single email file path |
| `get_thread_paths` | Get all paths in email thread |
| `read_email` | Read single email content (includes attachment metadata) |
| `read_thread` | Read entire email thread |
| `extract_attachments` | Extract specific attachments from email |
| `cleanup_attachments` | Clean up temporary attachment files |
๐ **[โ Detailed API Documentation](TOOLS.md)**
## ๐๏ธ How It Works
```
โโโโโโโโโโโโโโโ
โ 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](ARCHITECTURE.md)**
## ๐ Troubleshooting
### MCP server not found
**Solution**:
```bash
# 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**:
```bash
# 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
## ๐ Documentation
- **[TOOLS.md](TOOLS.md)** - Complete API reference for all MCP tools
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical architecture and database structure
- **[README_zh.md](README_zh.md)** - ไธญๆๆๆกฃ
## ๐ License
MIT License - see [LICENSE](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**:
- **Author**: Fatbobman (Xu Yang)
## โ Buy Me a Coffee
If you find this project helpful, consider buying me a coffee!
[](https://buymeacoffee.com/fatbobman)
---
**Made with โค๏ธ for the AI community**