AI导哈

邮件协议服务器

一个基于IMAP/SMTP协议的Gmail邮件管理服务器，提供邮件读取、发送、回复、搜索和定时处理功能，无需OAuth认证，仅需Gmail应用密码即可使用。

  • by Ralstonvaz
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Ralstonvaz/gmail-mcp-server

使用说明

Gmail MCP服务器（IMAP/SMTP）

一种模型上下文协议（MCP）服务器，为Claude提供了使用IMAP（用于读取）和SMTP（用于发送）协议与Gmail交互的工具。不需要谷歌云控制台或OAuth，只需要Gmail应用程序密码。功能包括阅读电子邮件、发送电子邮件、回复帖子、搜索和定时电子邮件处理。

特性

  • 📧 电子邮件管理：使用IMAP/SMTP列出、阅读、发送、回复和搜索电子邮件
  • 🔍 IMAP搜索：使用IMAP搜索条件进行高级电子邮件搜索
  • ⏰ 计划任务：在指定时间自动获取和处理未读电子邮件（默认：下午3点和7点）
  • 🔐 简单身份验证：使用Gmail应用程序密码（不需要OAuth2设置）
  • 🛡️ 错误处理：具有重试逻辑的全面错误处理
  • 📊 双格式：返回人类可读的文本摘要和结构化JSON数据
  • 🔒 安全：对所有连接使用TLS/SSL

先决条件

  • Node.js 18+和npm
  • 启用两步验证的Gmail帐户
  • Gmail应用程序密码（请参阅下面的设置说明）

安装

  1. 克隆或导航到项目目录：

    cd gmail-mcp-server

  2. 安装依赖项：

    npm install

  3. 构建项目：

    npm run build

Gmail应用程序密码设置

步骤1：启用两步验证

  1. 首选 Google帐户安全
  2. 在“登录谷歌”下，单击“两步验证”
  3. 按照提示启用两步验证

步骤2：生成应用程序密码

  1. 首选 应用程序密码
    • 或者导航：谷歌帐户>安全>两步验证>应用程序密码
  2. 选择“邮件”作为应用程序
  3. 选择“其他（自定义名称）”作为设备
  4. 输入“MCP服务器”作为名称
  5. 点击“生成”
  6. 复制16个字符的密码 （你只会看到一次！）

应用程序密码如下： abcd efgh ijkl mnop （空格是可选的）

配置

  1. 创建一个 .env 文件 在项目根目录中：
# Gmail IMAP/SMTP Credentials
GMAIL_USER=your.email@gmail.com
GMAIL_APP_PASSWORD=abcdefghijklmnop

# Scheduling Configuration
SCHEDULE_ENABLED=true
SCHEDULE_TIMES=15:00,19:00
TIMEZONE=Europe/Berlin
  1. 填写您的凭据：
    • GMAIL_USER：您的Gmail电子邮件地址
    • GMAIL_APP_PASSWORD：您生成的16个字符的应用程序密码
    • SCHEDULE_TIMES：HH:mm格式的逗号分隔时间（24小时）
    • TIMEZONE：您的时区（例如，“美洲/纽约”、“欧洲/伦敦”、“亚洲/东京”）

用法

发展模式

在热重载的开发模式下运行：

npm run dev

生产模式

构建并运行：

npm run build
npm start

类型检查

在不构建的情况下检查TypeScript类型：

npm run type-check

MCP工具

服务器为Claude提供了以下工具：

只读工具

  • gmail_list_emails：使用可选过滤器（未读、发件人、日期范围等）列出最近的电子邮件
  • gmail_read_email：通过IMAP UID读取完整的电子邮件内容
  • gmail_search_emails：使用IMAP搜索条件搜索电子邮件

写入工具

  • gmail_send_email：发送一封包含可选CC、BCC、HTML正文和附件的新电子邮件
  • gmail_reply_email：回复特定的电子邮件帖子
  • gmail_mark_read：将一封或多封电子邮件标记为已读

IMAP搜索条件

这 gmail_search_emails 和 gmail_list_emails 工具支持IMAP搜索条件：

通用标准

  • ["UNSEEN"] -未读电子邮件
  • ["SEEN"] -阅读电子邮件
  • ["FROM", "example@gmail.com"] -来自特定发件人的电子邮件
  • ["TO", "example@gmail.com"] -发送给特定收件人的电子邮件
  • ["SUBJECT", "meeting"] -主题为“会议”的电子邮件
  • ["SINCE", "01-Jan-2024"] -自某个日期（DD-MMM-YYYY）以来的电子邮件
  • ["BEFORE", "31-Dec-2024"] -约会前的电子邮件
  • ["ALL"] -所有电子邮件

组合标准

您可以组合多个条件：

  • ["UNSEEN", "FROM", "boss@company.com"] -老板的未读电子邮件
  • ["SINCE", "01-Jan-2024", "SUBJECT", "urgent"] -自1月1日以来主题为“紧急”的电子邮件

日期格式

日期应在 DD-MMM-YYYY 格式（例如，“2024年1月1日”、“2023年12月15日”）。

计划任务

服务器可以在指定时间自动获取和处理未读电子邮件。默认情况下，它每天在下午3点（15:00）和晚上7点（19:00）运行。

配置

产生 .env:

SCHEDULE_ENABLED=true
SCHEDULE_TIMES=15:00,19:00
TIMEZONE=Europe/Berlin

定制

您可以在 .env 文件。时间应该在 HH:mm 格式（24小时）：

SCHEDULE_TIMES=09:00,12:00,18:00,21:00

要禁用日程安排，请执行以下操作：

SCHEDULE_ENABLED=false

计划任务行为

当计划任务运行时，它：

  1. 使用IMAP获取过去24小时内未读的电子邮件
  2. 将摘要记录到控制台
  3. 输出结构化JSON数据以进行潜在的自动处理

您可以在中扩展调度程序 src/scheduler.ts 添加自定义自动处理规则（例如，自动分类、自动回复、自动转发）。

错误处理

服务器包括全面的错误处理：

  • 身份验证错误：清除带有设置说明的消息
  • 连接错误：使用指数回退自动重试
  • 验证错误：详细的字段级错误消息
  • 未找到错误：特定资源标识

IMAP/SMTP配置

服务器使用以下Gmail服务器设置：

  • 互联网邮件访问协议: imap.gmail.com:993 （SSL/TLS）
  • SMTP: smtp.gmail.com:587 （TLS）

这些是自动配置的，应该适用于任何启用了两步验证和应用程序密码的Gmail帐户。

故障排除

“IMAP连接错误”或“SMTP验证失败”

  • 验证您的 GMAIL_USER 和 GMAIL_APP_PASSWORD 在 .env
  • 确保您使用的是应用程序密码（而不是常规Gmail密码）
  • 检查您的Google帐户是否启用了两步验证
  • 验证是否为“邮件”生成了应用程序密码

“身份验证失败”

  • 确保您使用的是16个字符的应用程序密码（而不是常规密码）
  • 如果需要，重新生成应用程序密码
  • 确保没有多余的空间 .env 文件

“未找到电子邮件”错误

  • 验证指定邮箱中是否存在UID
  • 检查您是否使用了正确的邮箱名称（默认为“收件箱”）
  • UID是特定于邮箱的，如果电子邮件被移动，UID可能会发生变化

计划任务未运行

  • 验证 SCHEDULE_ENABLED=true 在 .env
  • 检查 SCHEDULE_TIMES 格式正确(HH:mm)
  • 确保服务器持续运行（而不仅仅是单个请求）
  • 验证 TIMEZONE 设置正确（使用IANA时区名称）

连接超时

  • 检查您的互联网连接
  • 验证Gmail IMAP/SMTP访问未被防火墙阻止
  • 某些网络可能会阻止IMAP/SMTP端口-考虑使用VPN或其他网络

项目结构

gmail-mcp-server/
├── src/
│   ├── index.ts              # MCP server initialization
│   ├── email/
│   │   ├── imap-client.ts    # IMAP connection for reading
│   │   ├── smtp-client.ts    # SMTP connection for sending
│   │   └── types.ts          # TypeScript interfaces
│   ├── tools/
│   │   ├── list-emails.ts    # List emails tool
│   │   ├── read-email.ts     # Read email tool
│   │   ├── send-email.ts     # Send email tool
│   │   ├── reply-email.ts    # Reply tool
│   │   ├── search-emails.ts  # Search tool
│   │   └── mark-read.ts      # Mark as read tool
│   ├── scheduler.ts          # Cron job configuration
│   └── utils/
│       ├── errors.ts         # Error handling
│       └── formatters.ts    # Response formatting
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

与Gmail API版本的差异

此IMAP/SMTP版本：

  • ✅ 不需要OAuth2设置 -只需使用应用程序密码
  • ✅ 无谷歌云控制台 -无需创建项目
  • ✅ 更简单的身份验证 -仅限用户名和应用程序密码
  • ✅ 直接协议访问 -使用标准电子邮件协议
  • ⚠️ 无草稿管理 -IMAP/SMTP不支持草稿
  • ⚠️ 不同的搜索语法 -使用IMAP搜索条件而不是Gmail搜索

安全说明

  • 永不承诺 .env 文件 到版本控制（它在 .gitignore)
  • 确保您的应用密码安全 -它允许访问您的Gmail帐户
  • 使用特定于环境的凭据 用于开发、分期和生产
  • 重新生成应用程序密码 如果他们曾经妥协
  • 应用程序密码是特定于帐户的 -每个用户都需要自己的

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

支持

对于问题、疑问或功能请求，请在存储库上打开问题。

相关 MCP