Kola Mail MCP

电子邮件智能MCP服务器

基于人工智能的电子邮件智能分析服务器，适用于模型上下文协议（MCP）。为Claude提供工具，以自动分析、分类、优先排序并从您的电子邮件中提取可操作的智能信息。

GitHub: Kolaborate-Platforms/kola-mail 翻译为中文是：“Kolaborate平台/kola邮件”

🚀 快速入门

安装

# Clone the repository
git clone https://github.com/Kolaborate-Platforms/kola-mail.git
cd kola-mail

# Install dependencies and build
bun install
bun run build

配置Claude桌面版

在您的Claude Desktop配置文件中添加：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "email-intelligence": {
      "command": "bun",
      "args": [
        "run",
        "/ABSOLUTE/PATH/TO/kola-mail/src/index.ts"
      ],
      "env": {
        "EMAIL_INTELLIGENCE_LOG_LEVEL": "info",
        "EMAIL_USER": "your-email@example.com",
        "EMAIL_PASSWORD": "your-password",
        "IMAP_HOST": "imap.example.com",
        "IMAP_PORT": "993",
        "IMAP_TLS": "true",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "USE_DEMO_EMAILS": "false"
      }
    }
  }
}

注替换 /ABSOLUTE/PATH/TO/kola-mail 使用你克隆仓库的实际路径。

重启Claude桌面版

重要要使更改生效，请完全退出（Cmd+Q）并重新启动 Claude Desktop。

测试服务器

在Claude Desktop中，可以说：

Test the email intelligence server

预期响应：

{
  "status": "ok",
  "message": "Email Intelligence MCP Server is running successfully!",
  "version": "1.0.0"
}

✨ 特点/功能

• 📧 实际电子邮件集成 - 通过IMAP从您的电子邮件服务器获取电子邮件
• 🎯 智能分类 - 5个类别（紧急/重要/常规/供参考/垃圾邮件）
• ⚡ 优先级评分 - 基于7+因素的0-10智能优先级评估
• ✅ 行动项提取 - 自动检测任务和截止日期
• 😊 情感分析 - 积极、中性或消极分类
• 💬 回应建议 - 人工智能生成的上下文回复
• 📤 发送电子邮件 - 通过SMTP发送电子邮件
• 🚀 快速缓存 - 基于内存的LRU缓存，有效期为5分钟
• 🔒 安全 - SSL/TLS加密，无永久存储

🛠️ 可用工具

1. test_server

进行健康检查以确认服务器正在运行。

使用方法:

Test the email intelligence server

2. analyze_emails

利用人工智能技术分析您收件箱中的电子邮件。

参数:

• emailSource“收件箱”、“未读”、“最近”或“自定义”
• limit （可选）：要分析的最大邮件数（默认：50，最大：200）
• since （可选）：ISO 日期，仅分析此日期之后的电子邮件
• includeBody （可选）：包含全身（默认：否）
• filter （可选）：按发件人/主题/关键词筛选

使用示例：

Analyze my unread emails

Analyze my emails from the last 7 days

Show me all urgent emails in my inbox

退货：

{
  "emails": [
    {
      "id": "msg_123",
      "from": "ceo@company.com",
      "subject": "Urgent: Q4 Report Needed",
      "analysis": {
        "category": "urgent",
        "priority": 9.5,
        "sentiment": "neutral",
        "actionItems": [
          {
            "text": "Send the Q4 report",
            "priority": 9.5,
            "deadline": "2025-10-22T17:00:00Z"
          }
        ],
        "hasDeadline": true,
        "keyTopics": ["report", "deadline"],
        "reasoning": "Category: contains urgent keywords..."
      }
    }
  ],
  "summary": {
    "totalAnalyzed": 1,
    "urgentCount": 1,
    "actionItemCount": 1,
    "avgPriority": 9.5
  }
}

3. get_priority_emails

返回按优先级排序的电子邮件，并可提供回复建议（可选）。

参数：

• count （可选）：电子邮件数量（默认：10，最大：50）
• minPriority （可选）：最小优先级 0-10（默认：7）
• categories （可选）：按类别筛选
• includeSuggestions （可选）：包含AI回复建议

使用示例：

Show me my top 5 most important emails

Get my urgent emails with response suggestions

4. send_email

通过SMTP从您配置的电子邮件账户发送邮件。

参数：

• to收件人电子邮箱（多个时请用逗号分隔）
• subject电子邮件主题
• body邮件正文（纯文本）
• html （可选）：HTML 正文
• inReplyTo （可选）：用于线程的消息ID
• references （可选）：线程引用

使用示例：

Send an email to john@example.com saying:
Subject: Meeting Follow-up
Body: Thanks for the meeting today. I'll send the report by Friday.

🎯 智能引擎

类别分类

优先级评分（0-10）

基础分数5（中立）

修饰符:

• 类别紧急 +4，重要 +2，供参考 -2，垃圾邮件 -5
• 行动项目/待办事项每件商品+1.5（最多+6）
• 截止日期临近:

- 今天：+3 - 1-3天：+2 - 4-7天：+1

• 发送者重要性：

- 首席执行官/高管团队：+3 - 经理：+2 - 客户：+2 - VIP名单：+1

• 电子邮件年龄>48小时未读+2，>24小时未读+1
• 关键词“需要做决定”+2，“请回复”+1

优先级范围：

• 九到十🔥 放下一切，立即回应
• 7-8⚡ 高优先级，今日回复
• 5-6📌 正常，2天内回复
• 3-4📋 低优先级，方便时回复
• 0-2🗑️ 非常低，可忽略

行动项目检测

使用20多种模式自动提取行动项：

• 直接请求：“请……”，“你能……吗”，“可以……吗”
• 正式请求：“敬请……”，“请求您……”
• 明确的条目：“待办事项:”，“待办:”，“任务:”
• 基于截止日期的：“在周五之前……”，“截止日期为……”，“最后期限……”

情感分析

基于关键词的分类：

• 积极的谢谢，感激，优秀，很棒，成功
• 否定的问题，议题，错误，失望，失败
• 中立更新、信息、会议、日程

🔧 配置

环境变量

设定于 .env 文件或Claude Desktop配置：

# Email Account (Required for real emails)
EMAIL_USER=your-email@example.com
EMAIL_PASSWORD=your-password

# IMAP Configuration (Incoming)
IMAP_HOST=imap.example.com
IMAP_PORT=993
IMAP_TLS=true

# SMTP Configuration (Outgoing)
SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_SECURE=true

# Server Settings
EMAIL_INTELLIGENCE_LOG_LEVEL=info  # debug, info, warn, error
ANALYSIS_CACHE_TTL=300              # seconds (5 minutes)
ANALYSIS_MAX_EMAILS=200

# Mode
USE_DEMO_EMAILS=false               # true = demo data, false = real emails

常见的电子邮件服务提供商:

• Gmail（谷歌邮箱）IMAP： imap.gmail.com:993SMTP： smtp.gmail.com:465 （需要应用密码）
• Outlook/Office 365IMAP： outlook.office365.com:993SMTP： smtp.office365.com:587
• 自定义/cPanel使用您的托管服务提供商的IMAP/SMTP设置

定制化

编辑 src/config.ts 进行定制：

• 优先级评分权重
• 分类关键词
• VIP发送者列表
• 缓存设置

📊 架构

src/
├── index.ts                    # MCP server entry point
├── types.ts                    # TypeScript type definitions
├── config.ts                   # Configuration and constants
├── email/
│   └── client.ts               # IMAP/SMTP email client
├── intelligence/
│   ├── analyzer.ts             # Main analysis orchestrator
│   ├── categorizer.ts          # Category classification
│   ├── prioritizer.ts          # Priority scoring
│   ├── action-extractor.ts     # Action item detection
│   ├── sentiment.ts            # Sentiment analysis
│   └── response-generator.ts   # Response suggestions
├── tools/
│   ├── test-server.ts          # Health check tool
│   ├── analyze-emails.ts       # Email analysis tool
│   ├── get-priorities.ts       # Priority emails tool
│   └── send-email.ts           # Email sending tool
└── utils/
    ├── cache.ts                # LRU cache with TTL
    └── logger.ts               # Logging utility

💻 使用示例

示例1：早晨邮件分类处理

你“早上好！我最紧急的邮件是什么？”

克劳德：

1. 电话 get_priority_emails(minPriority=8)
2. 通过IMAP获取您的真实电子邮件
3. 回复：“您有2封紧急邮件：

- CEO要求提交第四季度报告（优先级：10/10） - 客户端错误报告（优先级：9/10）

示例2：行动项

你“我从邮件中有哪些待办事项？”

克劳德：

1. 电话 analyze_emails(emailSource="unread")
2. 提取带有截止日期的行动项
3. 按优先级返回有序列表

示例3：发送响应

你“回复那位CEO的邮件，说我将在今天下班前收到报告”

克劳德：

1. 生成适当的回应
2. 电话 send_email 带有专业回复
3. 通过SMTP从您配置的电子邮件账户发送

🧪 测试

运行单元测试

bun test

类型检查

bun run type-check

手动测试

# Run server in dev mode
bun run dev

# In another terminal, you can test MCP protocol

🐛 故障排除

服务器无法连接

症状“未收到结果”或连接错误

解决方案：

1. 重启Claude桌面版 - 必须完全退出（在 macOS 上按 Cmd+Q，或在 Windows/Linux 上选择退出），然后重新打开
2. 检查日志：

- macOS（发音为 /ˈmækOS/）： ~/Library/Logs/Claude/mcp-server-email-intelligence.log - Windows： %APPDATA%\Claude\Logs\mcp-server-email-intelligence.log - Linux： ~/.config/Claude/logs/mcp-server-email-intelligence.log

1. 验证配置路径 在 claude_desktop_config.json
2. 验证凭证 在环境变量中

IMAP/SMTP 连接错误

检查：

1. 凭证正确无误 .env 或者配置
2. IMAP/SMTP服务器可访问：

   telnet your-imap-host.com 993
   telnet your-smtp-host.com 465

1. 对于Gmail：使用应用密码，而不是您的常规密码
2. 防火墙允许连接

未找到电子邮件

可能的原因:

• 收件箱为空
• 过滤条件过于严格
• 演示模式已启用USE_DEMO_EMAILS=true）

尝试：

Analyze all emails in my inbox (limit 10)

演示模式 vs 实际模式

实模式 (制作)：

• 设置 USE_DEMO_EMAILS=false
• 从IMAP获取实际电子邮件
• 通过SMTP发送真实电子邮件

演示模式 （测试）：

• 设置 USE_DEMO_EMAILS=true
• 使用6封内置演示邮件
• 没有真实的电子邮件连接

🔒 安全

• ✅ 凭据存储在环境变量中（已添加到git忽略文件中）
• ✅ IMAP和SMTP的SSL/TLS加密
• ✅ 邮件内容不永久存储
• ✅ 分析结果临时缓存（TTL为5分钟）
• ✅ 日志输出到标准错误流（不影响MCP协议）

📈 性能

• 目标在1秒内分析50封电子邮件
• 缓存具有5分钟TTL的LRU（最近最少使用）算法
• 记忆1000封邮件仅需100MB
• 吞吐量每分钟1000+封电子邮件

🚀 开发

项目设置

bun install
bun run build

手表模式

bun --watch run src/index.ts

构建

bun run build

📝 资源

服务器公开了这些MCP资源：

• email://intelligence/rules - 当前的分类规则和关键词
• email://intelligence/stats - 缓存统计信息和性能指标

🎉 为何这如此特别

智能分析

• 超越简单的关键词匹配
• 多因素优先级评分
• 情境感知分类
• 截止日期检测与跟踪

真实邮件集成

• 直接IMAP/SMTP连接
• 无需第三方API
• 对您的数据拥有完全控制权
• 与任何电子邮件服务提供商兼容

克劳德整合（或“克劳德集成”）

• 原生MCP协议
• 无缝的对话流程
• 自然语言查询
• 情境化回应

📄 许可证

麻省理工学院（MIT）

👨‍💻 作者

卡尔文·马格齐 & 克劳德

______________________________________________________________________

版本1.0.0 状态✅ 准备就绪，可投入生产 许可证麻省理工学院（MIT）

🆘 支持

对于问题或疑问：

1. 检查一下 故障排除部分 上述
2. 查看您Claude日志目录中的日志（路径请参阅故障排除部分）
3. 验证配置中的（内容） claude_desktop_config.json
4. 首先使用演示模式进行测试： USE_DEMO_EMAILS=true
5. 打开一个问题（或：提交一个问题） 在GitHub上

🤝 贡献（或：参与贡献）

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

______________________________________________________________________

最后更新时间2025年10月22日