{"id":35051276,"url":"https://github.com/fatbobman/mail-mcp-bridge","last_synced_at":"2026-04-12T14:15:56.954Z","repository":{"id":330582112,"uuid":"1123251861","full_name":"fatbobman/mail-mcp-bridge","owner":"fatbobman","description":"Connect macOS Mail to AI through Model Context Protocol","archived":false,"fork":false,"pushed_at":"2025-12-27T04:01:20.000Z","size":1071,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-28T01:44:13.660Z","etag":null,"topics":["ai","ai-assistant","automation","claude","email","email-client","email-tools","integration","llm","macos","macos-mail","mcp","mcp-server","openai","productivity","python"],"latest_commit_sha":null,"homepage":"https://fatbobman.com","language":"Python","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/fatbobman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"fatbobman","thanks_dev":null,"custom":["https://afdian.com","https://www.paypal.com/paypalme/fatbobman"]}},"created_at":"2025-12-26T13:40:02.000Z","updated_at":"2025-12-27T09:55:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fatbobman/mail-mcp-bridge","commit_stats":null,"previous_names":["fatbobman/mail-mcp-bridge"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fatbobman/mail-mcp-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fatbobman%2Fmail-mcp-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fatbobman%2Fmail-mcp-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fatbobman%2Fmail-mcp-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fatbobman%2Fmail-mcp-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fatbobman","download_url":"https://codeload.github.com/fatbobman/mail-mcp-bridge/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fatbobman%2Fmail-mcp-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","ai-assistant","automation","claude","email","email-client","email-tools","integration","llm","macos","macos-mail","mcp","mcp-server","openai","productivity","python"],"created_at":"2025-12-27T09:33:30.515Z","updated_at":"2026-01-13T22:01:06.866Z","avatar_url":"https://github.com/fatbobman.png","language":"Python","funding_links":["https://buymeacoffee.com/fatbobman","https://afdian.com","https://www.paypal.com/paypalme/fatbobman"],"categories":[],"sub_categories":[],"readme":"# Mail MCP Bridge\n\n\u003e Connect macOS Mail to AI through Model Context Protocol (MCP)\n\n**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.\n\n\n**Demo: See it in action** (Click to watch)\n\n![Demo Video](https://github.com/user-attachments/assets/b9229493-8bdf-4995-9ca8-d5de55ec7144)\n\n*Shows: Copy Message-ID from Mail → AI analyzes email content*\n\n[🇨🇳 中文版](README_zh.md)\n\n## 🎯 What \u0026 Why\n\n**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.\n\n**The Solution**: Mail MCP Bridge lets AI directly read your emails through a simple workflow:\n\n- Copy Message-ID from Mail (one keyboard shortcut)\n- Paste to AI\n- AI analyzes email content instantly\n\n**Use Cases**:\n\n- 📋 Track project progress via email threads\n- 💼 Extract key information from business communications\n- 🔍 Summarize long email conversations\n- 📊 Extract structured data (requirements, feedback, commitments)\n- 🤝 Review conversation history\n- 📎 Analyze email attachments (invoices, reports, documents)\n\n## ✨ Features\n\n- 📧 **Direct Access** - AI reads your emails through MCP protocol\n- 🧵 **Thread Support** - Retrieve entire conversations with one Message-ID\n- 📎 **Attachment Extraction** - Extract email attachments for AI analysis (PDFs, documents, images)\n- 🎨 **Claude Code Plugins** - Pre-built commands and skills for intelligent email analysis\n- ⚡ **Fast** - Millisecond-level query response\n- 🎯 **Clean Text** - Optimized text extraction for AI (excludes HTML, embedded images)\n- 🔒 **Privacy First** - Runs locally, emails never leave your Mac\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- macOS 12.0+ (with Mail app)\n- Python 3.9+\n- MCP-compatible AI assistant (e.g., Claude Desktop)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/fatbobman/mail-mcp-bridge.git\ncd mail-mcp-bridge\n\n# Install MCP dependencies\npip3 install mcp\n```\n\n### Configure Claude Desktop\n\n1. **Find config location**:\n\n   ```bash\n   ~/Library/Application Support/Claude/claude_desktop_config.json\n   ```\n\n2. **Edit config** (create if doesn't exist):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"mail\": {\n         \"command\": \"python3\",\n         \"args\": [\n           \"/path/to/mail-mcp-bridge/src/mail_mcp_server.py\"\n         ]\n       }\n     }\n   }\n   ```\n\n   **Important**: Replace `/path/to/mail-mcp-bridge` with your actual project path.\n\n   **Optional**: Configure attachment temp directory (defaults to `/tmp/mail-mcp-attachments`):\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"mail\": {\n         \"command\": \"python3\",\n         \"args\": [\n           \"/path/to/mail-mcp-bridge/src/mail_mcp_server.py\"\n         ],\n         \"env\": {\n           \"MAIL_ATTACHMENT_PATH\": \"/tmp\"\n         }\n       }\n     }\n   }\n   ```\n\n3. **Restart Claude Desktop** (quit completely, then reopen)\n\n### Install Claude Code Plugins (Optional but Recommended)\n\nMail MCP includes ready-to-use **Claude Code plugins** that provide intelligent email analysis capabilities:\n\n**What you get**:\n\n- 🎯 **Smart Attachment Analysis** - Automatically detects important attachments (invoices, contracts, tax docs)\n- 🧵 **Thread Tracking** - Tracks document evolution across email conversations\n- 🚀 **3 Analysis Modes** - Quick/Interactive/Auto modes to optimize token usage\n- 📋 **Action Item Extraction** - Finds deadlines and tasks in emails\n\n**Install**:\n\n```bash\n# 1. Add the Mail MCP plugin marketplace\n/plugin marketplace add /path/to/mail-mcp-bridge/plugins\n\n# 2. Install the attachment analyzer\n/plugin install mail-attachment-analyzer@mail-mcp\n\n# 3. Restart Claude Code\n```\n\nReplace `/path/to/mail-mcp-bridge` with your actual installation path.\n\n**Usage**:\n\nAfter installation, the plugin works automatically:\n\n```\nYou: Analyze this email \u003cmessage-id@example.com\u003e\nAI: [Automatically detects attachments and analyzes intelligently]\n```\n\nOr use manual commands:\n\n```\n/mail-mcp:analyze-attachment\n```\n\n📖 **[→ Plugin Documentation](plugins/README.md)**\n\n### Setup Mail Quick Action\n\nAdd a \"Copy Message-ID\" button to Mail app:\n\n**Step-by-Step**:\n\n1. Open **Automator** (`⌘ + Space`, type \"Automator\")\n\n2. Create new **Quick Action**:\n   - File → New (`⌘ + N`)\n   - Select \"Quick Action\"\n   - Workflow receives current: **no input**\n   - in: **Mail.app**\n\n3. Add **Run Shell Script** action:\n   - Search \"Run Shell Script\" in left panel\n   - Drag to workflow area\n   - Shell: `/bin/bash**\n\n4. Copy script content:\n\n   ```bash\n   cat automator_script.sh\n   ```\n\n   Paste entire output into Automator script area\n\n5. Save as **\"Copy Message-ID\"**\n\n6. (Optional) Assign keyboard shortcut:\n   - System Settings → Keyboard → Keyboard Shortcuts\n   - Services → Mail → \"Copy Message-ID\"\n   - Add shortcut (e.g., `⌘ + ⇧ + C`)\n\n**Automator Setup Example**:\n\n![Automator setup example](images/automatic-setup.webp)\n\n**Test It**:\n\n1. Open Mail app\n2. Select any email\n3. Press your keyboard shortcut (if configured)\n4. You should hear a sound confirming Message-ID copied\n\n## 📖 Usage\n\n### Basic Workflow\n\n```\n1. Select email in Mail\n2. Press your keyboard shortcut (e.g., ⌘⇧C)\n3. Paste Message-ID to AI\n```\n\n### Example Conversations\n\n**Read Single Email**:\n\n```\nYou: Please analyze this email: \u003cmessage-id@example.com\u003e\n\nAI: I'll read that email for you...\n[AI reads and analyzes the email content]\n```\n\n**Read Email Thread**:\n\n```\nYou: What's the full conversation for \u003cmessage-id@example.com\u003e?\n\nAI: I'll retrieve the entire thread...\n[AI shows all emails in the conversation]\n```\n\n**Real-World Use Case**:\n\n```\nYou: Please summarize all communication with our business partner,\nincluding their requirements, promised timelines, and action items.\n\nAI: I'll read the relevant email threads and extract key information...\n[AI analyzes email content, organizes project progress, commitments, and action items]\n```\n\n**Extract Email Attachments**:\n\n```text\nYou: Extract and analyze the PDF invoice from this email: \u003cmessage-id@example.com\u003e\n\nAI: I can see this email has an invoice.pdf attachment (1.2MB). Let me extract it...\n[AI extracts attachment and analyzes the content]\n```\n\n## 🛠️ MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_email_path` | Get single email file path |\n| `get_thread_paths` | Get all paths in email thread |\n| `read_email` | Read single email content (includes attachment metadata) |\n| `read_thread` | Read entire email thread |\n| `extract_attachments` | Extract specific attachments from email |\n| `cleanup_attachments` | Clean up temporary attachment files |\n\n📖 **[→ Detailed API Documentation](TOOLS.md)**\n\n## 🏗️ How It Works\n\n```\n┌─────────────┐\n│  Mail App   │ Select email → Copy Message-ID (⌘⇧C)\n└──────┬──────┘\n       │\n       ↓ Message-ID\n┌─────────────┐\n│MCP Server   │ 1. Query Mail SQLite database\n│             │ 2. Locate .emlx file by ROWID\n│             │ 3. Parse email content\n│             │ 4. Extract plain text\n└──────┬──────┘\n       │\n       ↓ Structured Data\n┌─────────────┐\n│ AI Assistant│ Analyze email content\n└─────────────┘\n```\n\n🔧 **[→ Technical Architecture](ARCHITECTURE.md)**\n\n## 🐛 Troubleshooting\n\n### MCP server not found\n\n**Solution**:\n\n```bash\n# Verify the path in claude_desktop_config.json\ncat ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n\n# Restart Claude Desktop (quit completely, then reopen)\n```\n\n### Email not found\n\n**Possible causes**:\n\n1. Message-ID format incorrect (must include `\u003c \u003e`)\n2. Email deleted from Mail\n3. Email in different Mail account database\n\n### Permission denied\n\n**Solution**:\n\n```bash\n# Make scripts executable\nchmod +x *.py *.sh\n```\n\n## 🔒 Privacy \u0026 Security\n\n- ✅ **Local Processing**: All operations run locally on your Mac\n- ✅ **No External Servers**: No data sent to external servers\n- ✅ **No Telemetry**: No analytics or tracking\n- ✅ **Read-Only**: Only reads email data, never modifies\n\n## 📚 Documentation\n\n- **[TOOLS.md](TOOLS.md)** - Complete API reference for all MCP tools\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical architecture and database structure\n- **[README_zh.md](README_zh.md)** - 中文文档\n\n## 📝 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions welcome! Please feel free to submit a Pull Request.\n\n## 🌟 Acknowledgments\n\n- Built for the MCP (Model Context Protocol) ecosystem\n- Inspired by the need to bridge email and AI\n- Tested with Claude Desktop on macOS 26 (Tahoe)\n\n## 📮 Contact\n\n- **Issues**: \u003chttps://github.com/fatbobman/mail-mcp-bridge/issues\u003e\n- **Author**: Fatbobman (Xu Yang)\n\n## ☕ Buy Me a Coffee\n\nIf you find this project helpful, consider buying me a coffee!\n\n[![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/fatbobman)\n\n---\n\n**Made with ❤️ for the AI community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffatbobman%2Fmail-mcp-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffatbobman%2Fmail-mcp-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffatbobman%2Fmail-mcp-bridge/lists"}