JinDaGe - mail-mcp-bridge MCP Details

article

README

🚀 邮件MCP桥接器

邮件MCP桥接器通过模型上下文协议（MCP）将macOS邮件应用与人工智能连接起来，让AI助手（如Claude、ChatGPT）直接访问和分析你的邮件，无需手动导出邮件，只需从邮件中复制Message-ID并粘贴到AI即可。

🚀 快速开始

前提条件

macOS 12.0 及以上版本（需安装邮件应用）
Python 3.9 及以上版本
支持MCP的AI助手（如Claude Desktop）

安装

# 克隆仓库
git clone https://github.com/fatbobman/mail-mcp-bridge.git
cd mail-mcp-bridge

# 安装MCP依赖
pip3 install mcp

配置Claude Desktop

查找配置文件位置：

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

编辑配置文件（若文件不存在则创建）：

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

重要提示：请将/path/to/mail-mcp-bridge替换为你实际的项目路径。

可选配置：配置附件临时目录（默认为/tmp/mail-mcp-attachments）：

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

重启Claude Desktop（完全退出后重新打开）

安装Claude代码插件（可选但推荐）

邮件MCP包含了现成的Claude代码插件，可提供智能邮件分析功能： 功能特性：

🎯 智能附件分析 - 自动检测重要附件（发票、合同、税务文件等）
🧵 线程跟踪 - 跟踪邮件对话中的文档演变
🚀 三种分析模式 - 快速/交互/自动模式，优化令牌使用
📋 行动项提取 - 查找邮件中的截止日期和任务

安装步骤：

# 1. 添加邮件MCP插件市场
/plugin marketplace add /path/to/mail-mcp-bridge/plugins

# 2. 安装附件分析器
/plugin install mail-attachment-analyzer@mail-mcp

# 3. 重启Claude代码

请将/path/to/mail-mcp-bridge替换为你实际的安装路径。

使用方法：安装后，插件将自动工作：

你：分析这封邮件 <message-id@example.com>
AI：[自动检测附件并进行智能分析]

也可使用手动命令：

/mail-mcp:analyze-attachment

📖 → 插件文档

设置邮件快速操作

在邮件应用中添加“复制Message-ID”按钮： 详细步骤：

打开自动操作（⌘ + Space，输入“自动操作”）
创建新的快速操作：
- 文件 → 新建（⌘ + N）
- 选择“快速操作”
- 工作流程接收当前：无输入
- 在：邮件.app
添加运行Shell脚本操作：
- 在左侧面板中搜索“运行Shell脚本”
- 拖到工作流程区域
- 外壳：/bin/bash
复制脚本内容：

cat automator_script.sh

将整个输出粘贴到自动操作脚本区域 5. 保存为**“复制Message-ID”** 6. （可选）分配键盘快捷键： - 系统设置 → 键盘 → 键盘快捷键 - 服务 → 邮件 → “复制Message-ID” - 添加快捷键（如⌘ + ⇧ + C）

自动操作设置示例：

测试方法：

打开邮件应用
选择任意邮件
按下你的键盘快捷键（如果已配置）
你应该会听到确认Message-ID已复制的声音

✨ 主要特性

📧 直接访问 - AI通过MCP协议读取你的邮件
🧵 线程支持 - 使用一个Message-ID检索整个对话
📎 附件提取 - 提取邮件附件供AI分析（PDF、文档、图像等）
🎨 Claude代码插件 - 预构建的命令和技能，用于智能邮件分析
⚡ 快速响应 - 毫秒级查询响应
🎯 纯净文本 - 为AI优化文本提取（排除HTML、嵌入式图像）
🔒 隐私至上 - 本地运行，邮件不会离开你的Mac

📦 安装指南

安装步骤已在快速开始部分详细介绍，这里不再赘述。

💻 使用示例

基础用法

1. 在邮件中选择邮件
2. 按下你的键盘快捷键（如⌘⇧C）
3. 将Message-ID粘贴到AI

示例对话

读取单封邮件：

你：请分析这封邮件：<message-id@example.com>
AI：我将为你读取那封邮件...
[AI读取并分析邮件内容]

读取邮件线程：

你：<message-id@example.com>的完整对话是什么？
AI：我将检索整个对话...
[AI显示对话中的所有邮件]

实际应用场景：

你：请总结与我们商业伙伴的所有沟通，包括他们的要求、承诺的时间表和行动项。
AI：我将读取相关邮件线程并提取关键信息...
[AI分析邮件内容，整理项目进度、承诺和行动项]

提取邮件附件：

你：从这封邮件中提取并分析PDF发票：<message-id@example.com>
AI：我看到这封邮件有一个invoice.pdf附件（1.2MB）。让我提取它...
[AI提取附件并分析内容]

📚 详细文档

MCP工具

| 工具 | 描述 | |------|------| | get_email_path | 获取单封邮件文件路径 | | get_thread_paths | 获取邮件线程中的所有路径 | | read_email | 读取单封邮件内容（包括附件元数据） | | read_thread | 读取整个邮件线程 | | extract_attachments | 从邮件中提取特定附件 | | cleanup_attachments | 清理临时附件文件 |

📖 → 详细API文档

🔧 技术细节

工作原理

┌─────────────┐
│ 邮件应用   │ 选择邮件 → 复制Message-ID（⌘⇧C）
└──────┬──────┘
       │
       ↓ Message-ID
┌─────────────┐
│MCP服务器   │ 1. 查询邮件SQLite数据库
│             │ 2. 通过ROWID定位.emlx文件
│             │ 3. 解析邮件内容
│             │ 4. 提取纯文本
└──────┬──────┘
       │
       ↓ 结构化数据
┌─────────────┐
│ AI助手     │ 分析邮件内容
└─────────────┘

🔧 → 技术架构

🐛 故障排除

MCP服务器未找到

解决方案：

# 验证claude_desktop_config.json中的路径
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 重启Claude Desktop（完全退出后重新打开）

邮件未找到

可能原因：

Message-ID格式不正确（必须包含< >）
邮件已从邮件应用中删除
邮件位于不同的邮件账户数据库中

权限被拒绝

解决方案：

# 使脚本可执行
chmod +x *.py *.sh

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

🌟 致谢

为MCP（模型上下文协议）生态系统而构建
受连接邮件和AI需求的启发
在macOS 26（Tahoe）上使用Claude Desktop进行测试

📮 联系信息

问题反馈：https://github.com/fatbobman/mail-mcp-bridge/issues
作者：Fatbobman（徐洋）

☕ 请我喝咖啡

如果你觉得这个项目有帮助，不妨请我喝杯咖啡！

为AI社区用心打造 ❤️

mail-mcp-bridge