MCP邮件服务器

Name: MCP邮件服务器
Author: cristip73

作者：cristip732 星标更新：2025-08-28

安装使用来源：spider==github.com

项目介绍

Gmail MCP Server

这是一个模型上下文协议（MCP）服务器，它使Claude桌面应用（或其他支持MCP的应用）能够与Gmail进行交互，提供通过标准化接口读取、搜索和发送电子邮件的能力，以及其他更多功能。

与其他邮件MCP服务器有何不同？

除了标准的发送、读取、搜索等功能外，还支持回复所有人、抄送、密送、引用原始消息、转发邮件、创建、更新、列出和删除草稿、管理标签、标记邮件为已读或未读、归档；附件保存到您的文件夹。

我花费了很多时间来尽可能地模仿Gmail的行为。在回复中添加引用，在同一线程中回复和转发，类别管理（主要、社交、促销、更新、论坛）。

我还花了很多时间调整日期和时间以适应用户的时区。默认是GMT+0。所以当你请求昨天的邮件时，它会根据用户的时区进行调整。

最佳实践：当您要求Claude发送电子邮件时，请让它写好邮件/回复/转发并将其保存为草稿。您可以审阅后再手动确认发送。至少对于重要邮件来说是这样。

安装

选项1：使用NPX（推荐）

您可以直接使用npx运行MCP邮件服务器，而无需全局安装：

npx @cristip73/email-mcp

对于认证（首次设置）：

npx @cristip73/email-mcp auth

选项2：克隆并本地安装

克隆并安装：

git clone https://github.com/cristip73/MCP-email-server.git
cd MCP-email-server
npm install

构建服务器：
```
npm run build
```
使用Gmail进行认证：
```
npm run auth
```
这将打开一个浏览器窗口以使用您的Google账户进行认证。
使包对Claude可用：
```
npm link
```

设置Google Cloud OAuth凭证

在使用此应用程序之前，您需要在Google Cloud中设置OAuth凭证：

访问Google Cloud控制台
创建一个新的项目或选择一个现有的项目
导航至“API和服务”>“库”
搜索并启用“Gmail API”
转到“API和服务”>“凭据”
点击“创建凭据”>“OAuth客户端ID”
选择“桌面应用”作为应用类型
命名您的OAuth客户端（例如，“MCP邮件客户端”）
下载凭证JSON文件

下载后：

将文件重命名为gcp-oauth.keys.json
放置在以下位置之一：
- 您当前的工作目录（它将被自动复制）
- 全局配置目录~/.email-mcp/gcp-oauth.keys.json

使用Claude

Claude桌面

如何将MCP服务器添加到Claude桌面：

打开Claude桌面 > 单击顶部菜单中的“Claude” > 单击“设置” > 单击“开发者模式” > 选择“编辑配置” > 使用光标或其他文本编辑器编辑claude_desktop_config.json文件。

包含NPX的`claude_desktop_config.json`文件示例：

{
  "mcpServers": {
    "email-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cristip73/email-mcp"
      ],
      "env": {
          "TIME_ZONE": "GMT+2",
          "DEFAULT_ATTACHMENTS_FOLDER": "/Users/username/CLAUDE/Attachments"
      }     
    }
  }
}

保存文件并重新启动Claude桌面。就这样！享受不再需要手动编写电子邮件信息的乐趣。只需让Claude为您完成即可。

如果您正确完成了所有步骤，您应该在Claude桌面 > 设置 > 开发者模式中的MCP服务器列表中看到email-server。如果没有，您将收到错误消息。如果您不确定，请向AI寻求帮助。

重要提示：将DEFAULT_ATTACHMENTS_FOLDER设置为系统上的有效路径。

重要提示：将TIME_ZONE设置为您的本地时区，格式为GMT（例如：GMT+2，GMT-5等）。否则，电子邮件的日期和时间将会不准确，默认设置为GMT+0。

该服务器即使没有TIME_ZONE或DEFAULT_ATTACHMENTS_FOLDER也能工作，但您的时区将不准确，且无法保存附件。

对于Claude代码编辑器，您可以通过运行以下命令添加服务器：

claude mcp add email-server -- /path/to/email-server/build/index.js

目的

此服务器连接Claude AI与Gmail API，允许Claude：

发送电子邮件和回复（包括回复所有人、抄送和密送、引用原始消息、转发电子邮件等）
使用高级过滤器搜索和检索电子邮件
读取电子邮件内容和附件
处理Gmail类别和标签
将附件保存到系统上的特定文件夹
创建、更新、列出和删除草稿
管理标签
标记邮件为已读、未读、归档等
列出电子邮件中的附件
将电子邮件中的附件保存到系统上的特定文件夹

不幸的是，Gmail不支持计划发送电子邮件。如果支持的话，这将非常棒。

通过实现模型上下文协议，它赋予了Claude执行经过身份验证的Gmail操作的能力，同时保持安全性和隐私性。

项目结构

src/
├── index.ts                 # 应用程序入口点和服务器初始化
├── server.ts                # MCP服务器实现
├── client-wrapper.ts        # 支持多账户的Gmail API客户端封装
├── tool-handler.ts          # 工具注册和请求路由
├── prompt-handler.ts        # 提示管理和模板系统
├── version.ts               # 版本信息
├── utils.ts                 # 用于日期、电子邮件等的共享实用工具
├── timezone-utils.ts        # 时区处理和配置
└── tools/                   # 按领域实现的工具
    ├── email-read-tools.ts  # 阅读电子邮件的工具
    ├── email-send-tools.ts  # 发送、回复和转发电子邮件的工具
    ├── email-search-tools.ts # 搜索和过滤电子邮件的工具
    ├── email-label-tools.ts # 管理标签和消息状态的工具
    ├── email-attachment-tools.ts # 列出和保存附件的工具
    ├── email-draft-tools.ts # 管理电子邮件草稿的工具
    └── timezone-tool.ts     # 验证时区配置的工具

核心组件

index.ts：应用程序的入口点，处理认证和服务器初始化
server.ts：实现MCP服务器功能，注册工具和提示处理器
client-wrapper.ts：封装Gmail API功能，实现类别支持、消息转换和多账户处理
tool-handler.ts：将工具请求路由到适当的处理器，并格式化响应
prompt-handler.ts：管理常见Gmail操作的模板和示例
utils.ts：提供日期格式化、电子邮件创建、内容提取和适当UTF-8编码的实用函数
timezone-utils.ts：处理时区解析、转换和格式化，以便一致的日期处理
tools/：包含按领域实现的电子邮件操作工具
- email-read-tools.ts：阅读电子邮件和提取内容的工具以此类推...

配置

服务器支持以下配置：

TIME_ZONE：时区配置，如'GMT+2'或'GMT-5'（默认：'GMT+0'）
DEFAULT_ATTACHMENTS_FOLDER：可以保存电子邮件附件的目录路径（例如，'/Users/username/CLAUDE/attachments'）

重要路径信息

当您在文档中看到~/.email-mcp/credentials.json时，这意味着：

macOS：/Users/[your-username]/.email-mcp/credentials.json
Linux：/home/[your-username]/.email-mcp/credentials.json
Windows：C:\Users\[your-username]\.email-mcp\credentials.json

同样适用于~/.email-mcp/gcp-oauth.keys.json。

这些文件存储在用户主目录下的隐藏目录中。应用程序在认证过程中会自动创建这个目录。

功能

邮件操作

发送邮件：发送新邮件，支持抄送、密送和附件
回复：回复现有邮件，保持线程上下文
回复所有人：回复线程中的所有收件人，过滤掉自己的地址
转发：转发邮件给其他收件人，带有原始头和格式
读取邮件：检索并显示邮件内容、头和附件
搜索邮件：使用Gmail查询语法搜索邮件，具有增强功能

草稿管理

创建草稿：保存邮件草稿供以后编辑或发送
列出草稿：查看所有保存的草稿，支持分页
更新草稿：编辑现有草稿，完全修改内容
发送草稿：将保存的草稿转换为已发送邮件
删除草稿：移除不再需要的草稿

高级功能

分页：通过pageToken支持大型结果集导航
Gmail类别：按Gmail类别筛选（主要、社交、促销等）
时间筛选：按预定义的时间段筛选（今天、昨天、过去24小时）
未读状态：自动处理未读邮件筛选
HTML内容：处理和显示HTML和纯文本邮件内容
线程上下文：维护邮件线程以保持正确的对话上下文
多账户支持：自动处理多个发送地址和别名
智能回复地址：基于原始收件人选择正确的发送地址
UTF-8编码：主题和正文内容中的国际字符正确编码
安全附件处理：将附件限制保存到指定文件夹，并进行路径验证

标签管理

自定义标签：创建、更新和删除自定义标签
标签可见性：控制消息列表和标签列表中的标签可见性
标签颜色：配置文本和背景颜色以进行视觉组织
消息状态：标记消息为已读/未读，归档/取消归档消息
垃圾箱管理：将消息移动到垃圾箱

时区支持

显示和查询邮件：以用户的本地时区显示和查询邮件
时区验证：检查配置的时区并查看当前时间调整
可配置偏移量：支持自定义GMT偏移量（GMT+2，GMT-5等）
一致格式化：所有时间戳都以配置的时区显示
日期计算：搜索过滤器如“今天”和“昨天”正确调整时区

附件管理

列出附件：查看邮件中的所有附件及其完整元数据（名称、大小、类型）
保存附件：将附件安全地保存到配置的DEFAULT_ATTACHMENTS_FOLDER
路径安全：验证和规范化以防止路径遍历攻击
文件完整性：保存文件时进行大小验证和错误报告
自动选择：在未提供特定附件ID时的智能处理
多附件支持：支持具有多个附件的邮件
文件夹创建：在保存附件时自动创建必要的目录
错误处理：全面处理失败的附件操作

可用工具

发送邮件

send_email

发送一封新的电子邮件。

参数：

to：收件人的电子邮件地址数组（必需）
subject：电子邮件主题（必需）
body：电子邮件正文内容（必需）
cc：抄送收件人数组
bcc：密送收件人数组
inReplyTo：要回复的消息ID
threadId：要添加消息的线程ID

回复所有人邮件

reply_all_email

回复邮件并包括所有原始收件人（TO和CC）。

参数：

messageId：要回复的消息ID（必需）
body：电子邮件正文内容（必需）
additionalRecipients：要在回复中包含的额外收件人
excludeRecipients：从回复中排除的收件人
from：要用作发件人的特定发送地址（可选）

该工具自动处理：

包括所有原始收件人（TO和CC）
排除自己的电子邮件地址以防止自我回复
设置适当的电子邮件头以保持线程
根据原始收件人使用正确的FROM地址

转发邮件

forward_email

将邮件转发给其他收件人。

参数：

messageId：要转发的消息ID（必需）
to：要转发邮件的收件人列表（必需）
additionalContent：在转发邮件前添加的内容
cc：抄送收件人列表
from：要用作发件人的特定发送地址（可选）

该工具自动处理：

使用适当的头格式化转发邮件
如果尚未存在，则在主题前添加“Fwd:”前缀
包含原始邮件头（From, Date, Subject, To, Cc）
维护与原始邮件的线程上下文
从收件人列表中排除自己的电子邮件地址

列出发送账户

list_send_as_accounts

列出可用于发送电子邮件的所有账户和电子邮件地址。

参数：无

所有发送账户及其属性的列表
默认账户信息
验证状态和显示名称的信息

获取最近的邮件

get_recent_emails

获取最近的邮件，支持时间过滤器、类别和已读状态。

参数：

hours：回溯的小时数
maxResults：要返回的最大结果数（默认：25）
query：附加的Gmail搜索查询
pageToken：下一页结果的令牌
category：按Gmail类别筛选（主要、社交、促销、更新、论坛）
timeFilter：预定义的时间过滤器（今天、昨天、过去24小时）
autoFetchAll：自动获取所有结果（最多100个），无需分页

读取邮件

read_email

通过ID读取特定邮件并提取其内容。

参数：

messageId：要检索的邮件消息ID（必需）

搜索邮件

search_emails

使用Gmail查询语法搜索邮件，支持类别和时间过滤器。

参数：

query：Gmail搜索查询（必需）
maxResults：要返回的最大结果数（默认：25）
pageToken：下一页结果的令牌
category：按Gmail类别筛选（主要、社交、促销、更新、论坛）
timeFilter：预定义的时间过滤器（今天、昨天、过去24小时）
autoFetchAll：自动获取所有结果（最多100个），无需分页

标签管理工具

列出标签

list_labels

列出用户邮箱中的所有标签。

参数：无

获取标签

get_label

获取特定标签的详细信息。

参数：

labelId：要检索的标签ID（必需）

创建标签

create_label

在用户邮箱中创建新的标签。

参数：

name：要创建的标签名称（必需）
messageListVisibility：控制标签在消息列表中的可见性（show或hide）
labelListVisibility：控制标签在标签列表中的可见性（labelShow、labelShowIfUnread或labelHide）
textColor：文本颜色的十六进制格式（例如，#000000）
backgroundColor：背景颜色的十六进制格式（例如，#ffffff）

更新标签

update_label

更新现有标签。

参数：

labelId：要更新的标签ID（必需）
name：标签的新名称
messageListVisibility：控制标签在消息列表中的可见性（show或hide）
labelListVisibility：控制标签在标签列表中的可见性（labelShow、labelShowIfUnread或labelHide）
textColor：文本颜色的十六进制格式（例如，#000000）
backgroundColor：背景颜色的十六进制格式（例如，#ffffff）

删除标签

delete_label

从用户邮箱中删除标签。

参数：

labelId：要删除的标签ID（必需）

修改标签

modify_labels

向消息添加或移除标签。

参数：

messageId：要修改的消息ID（必需）
addLabelIds：要添加到消息的标签ID数组
removeLabelIds：要从消息中移除的标签ID数组

消息管理工具

标记为已读

mark_as_read

将消息标记为已读。

参数：

messageId：要标记为已读的消息ID（必需）

标记为未读

mark_as_unread

将消息标记为未读。

参数：

messageId：要标记为未读的消息ID（必需）

归档消息

archive_message

归档消息（从收件箱中移除）。

参数：

messageId：要归档的消息ID（必需）

取消归档消息

unarchive_message

将消息移回到收件箱。

参数：

messageId：要移回到收件箱的消息ID（必需）

移动消息到垃圾箱

trash_message

将消息移动到垃圾箱。

参数：

`messageId