使用说明

Gmail MCP服务器

模型上下文协议（MCP）服务器，使Claude Desktop App（或支持MCP的任何其他应用程序）能够与Gmail交互，通过标准化界面提供阅读、搜索和发送电子邮件等功能。

与其他用于电子邮件服务器的MCP有什么不同？

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

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

我还花了很多时间将日期和时间调整到用户的时区。默认值为GMT+0。因此，当您询问昨天的电子邮件时，它将根据用户的时区进行调整。

最佳实践：当你让克劳德发电子邮件时，让他写电子邮件/回复/转发，并将其另存为草稿。您可以查看它并手动发送确认。至少对于重要的电子邮件。

安装

选项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凭据：

首选谷歌云控制台
创建新项目或选择现有项目
导航到“API和服务”>“库”
搜索并启用“Gmail API”
转到“API和服务”>“凭据”
点击“创建凭据”>“OAuth客户端ID”
选择“桌面应用程序”作为应用程序类型
命名您的OAuth客户端（例如，“MCP电子邮件客户端”）
下载凭据JSON文件

下载后：

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

与Claude一起使用

克劳德桌面

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

打开Claude Desktop>点击顶部菜单中的“Claude”>点击“设置”>单击“开发人员模式”>选择“编辑配置”>使用Cursor或任何其他文本编辑器编辑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 Desktop。就是这样！享受不再需要手写电子邮件的乐趣。就让克劳德帮你做吧。

如果您正确完成了所有步骤，您应该在Claude Desktop>设置>开发人员模式中的MCP服务器列表中看到电子邮件服务器。如果你不这样做，你会收到一条错误消息。如果你不确定，请向AI寻求帮助。

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

重要提示：将TIME_ZONE设置为GMT格式的本地时区。例如：GMT+2、GMT-5等。否则，电子邮件的日期和时间将关闭，Gmail默认设置为GMT+0。

服务器也可以在没有任何TIME_ZONE或DEFAULT_ATTACHMENTS_FOLDER的情况下工作，但您的时区将关闭，您将无法保存附件。

对于Claude Code Editor，您可以通过运行以下命令添加服务器：

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

目的

该服务器将Claude AI与Gmail API连接起来，允许Claude：

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

不幸的是，Gmail不支持定时电子邮件。如果真是这样，那就太好了。

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

项目结构

src/
├── index.ts                 # Entry point and server initialization
├── server.ts                # MCP server implementation
├── client-wrapper.ts        # Gmail API client wrapper with multi-account support
├── tool-handler.ts          # Tool registration and request routing
├── prompt-handler.ts        # Prompt management and template system
├── version.ts               # Version information
├── utils.ts                 # Shared utilities for dates, emails, etc.
├── timezone-utils.ts        # Timezone handling and configuration
└── tools/                   # Tool implementations by domain
    ├── email-read-tools.ts  # Tools for reading emails
    ├── email-send-tools.ts  # Tools for sending, replying and forwarding emails
    ├── email-search-tools.ts # Tools for searching and filtering emails
    ├── email-label-tools.ts # Tools for managing labels and message states
    ├── email-attachment-tools.ts # Tools for listing and saving attachments
    ├── email-draft-tools.ts # Tools for managing email drafts
    └── timezone-tool.ts     # Tool for verifying timezone configuration

核心组件

index.ts：应用程序的入口点，处理身份验证和服务器初始化
server.ts：实现MCP服务器功能，注册工具和提示的处理程序
客户端-抓取器：包装Gmail API功能，实现类别支持、邮件转换和多帐户处理
tool-handler.ts：将工具请求路由到适当的处理程序并格式化响应
prompt-handler.ts：管理常用Gmail操作的模板和示例
utils.ts：提供用于日期格式化、电子邮件创建、内容提取和正确UTF-8编码的实用程序功能
时区-实用工具：处理时区解析、转换和格式化，以实现一致的日期处理
工具/：包含电子邮件操作的域特定实现
- 电子邮件read-tools.ts：用于阅读电子邮件和提取内容的工具
- 电子邮件发送到ols.ts：用于发送电子邮件、回复和转发的工具
- 电子邮件搜索tools.ts：用于搜索和过滤电子邮件的工具
- email-label-tools.ts：用于管理标签和消息状态（已读/未读、存档/未存档）的工具
- 电子邮件附件tools.ts：用于列出附件并将其安全保存到磁盘的工具
- 电子邮件draft-tools.ts：用于创建、更新、列出和发送电子邮件草稿的工具
- 时区到ol.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
视窗: C:\Users\[your-username]\.email-mcp\credentials.json

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

这些文件存储在用户主文件夹中的隐藏目录中。应用程序在身份验证过程中自动创建此目录。

特性

电子邮件操作

发送电子邮件：发送支持CC、BCC和附件的新电子邮件
回复：在保持线程上下文的同时回复现有电子邮件
全部答复：在筛选自己的地址的同时，回复一个帖子中的所有收件人
转发：将带有原始标题和格式的电子邮件转发给其他收件人
阅读电子邮件：检索和显示电子邮件内容、标题和附件
搜索电子邮件：使用具有增强功能的Gmail查询语法搜索电子邮件

草案管理

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

高级功能

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

标签管理

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

时区支持

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

附件管理

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

可用工具

发送电子邮件

send_email

发送一封新的电子邮件。

参数：

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

回复所有电子邮件

reply_all_email

回复电子邮件并包括所有原始收件人（收件人和抄送人）。

参数：

messageId：要回复的邮件的ID（必填）
body：电子邮件正文内容（必填）
additionalRecipients：回复中要包含的其他收件人
excludeRecipients：要从答复中排除的收件人
from：用作发件人的特定电子邮件地址（可选）

该工具会自动处理：

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

转发电子邮件

forward_email

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

参数：

messageId：要转发的消息的ID（必填）
to：要转发电子邮件的收件人列表（必填）
additionalContent：转发邮件前要添加的其他内容
cc：CC收件人列表
from：用作发件人的特定电子邮件地址（可选）

该工具会自动处理：

使用正确的标头格式化转发的邮件
如果主题中尚未存在“Fwd:”前缀，则添加该前缀
包括原始电子邮件标题（发件人、日期、主题、收件人、抄送）
使用原始电子邮件维护线程上下文
从收件人列表中排除您自己的电子邮件地址

以帐户身份发送列表

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：要移至回收站的邮件的ID（必填）

草稿管理工具

创建草稿

create_draft

在不发送的情况下创建新的电子邮件草稿。

参数：

to：收件人电子邮件地址数组（必填）
subject：电子邮件主题（必填）
body：电子邮件正文内容（必填）
cc：CC收件人数组
bcc：BCC收件人数组
from：用作发件人的特定电子邮件地址

获取草稿

get_draft

检索特定草稿的内容。

参数：

draftId：要检索的草稿的ID（必填）

列出草稿

list_drafts

列出电子邮件帐户中的所有草稿。

参数：

maxResults：要返回的最大草稿数（默认值：20）
pageToken：下一页结果的标记
query：搜索草稿筛选器

更新草稿

update_draft

更新现有草稿的内容。

参数：

draftId：要更新的草稿ID（必填）
to：收件人电子邮件地址的新列表（必填）
subject：新电子邮件主题（必填）
body：新电子邮件正文内容（必填）
cc：CC收件人的新列表
bcc：BCC收件人的新列表
from：用作发件人的新特定电子邮件地址

删除草稿

delete_draft

永久删除草稿。

参数：

draftId：要删除的草稿的ID（必填）

发送草稿

send_draft

发送现有草稿。

参数：

draftId：要发送的草稿的ID（必填）

时区工具

获取时区信息

get_timezone_info

显示系统中配置的时区信息。

参数：无

退货：

配置的时区（来自TIME_ZONE变量）
计算偏移量（小时）
当前日期和时间已调整为时区
用于比较的UTC当前日期和时间

附件管理工具

列出附件

list_attachments

列出电子邮件中的所有附件。

参数：

messageId：要列出附件的邮件的ID（必需）

退货：

所有附件及其详细信息（名称、类型、大小）的列表
电子邮件中的附件计数

保存附件

save_attachment

将电子邮件中的附件保存到配置的DEFAULT_ATTACHMENTS_FOLDER。

参数：

messageId：包含附件的邮件的ID（必填）
attachmentId：附件的ID（如“f_mamj3yyo1”）或附件的文件名（如“document.pdf”）。如果邮件只有一个附件，则可选。
targetPath：保存附件的文件名或相对路径（将保存在DEFAULT_ATTACHMENTS_FOLDER中）

该工具自动执行以下操作：

下载附件（可以通过ID或文件名找到）
将其保存到DEFAULT_ATTACHMENTS_FOLDER中的指定路径
验证文件完整性
如果不存在，则创建必要的目录
防止路径遍历攻击（所有文件都保存在DEFAULT_ATTACHMENTS_FOLDER中）

示例提示

“发送电子邮件至john@example.com主题为“明天见面”
“获取我过去24小时的电子邮件”
“搜索来自的电子邮件jane@example.com"
“在我的主要类别中查找昨天的未读电子邮件”
“显示今天收到的包含'折扣'的促销电子邮件”
“创建一个名为‘Project X’的蓝色背景新标签”
“显示我的所有Gmail标签”
“将此电子邮件标记为未读”
“将此通讯中的所有电子邮件存档”
“将此电子邮件移至我的“重要”标签”
“为团队起草一份关于即将召开的会议的草稿”
“显示我保存的所有草稿”
“更新我的草稿以包含新信息”
“发送我之前创建的草稿”
“删除我不再需要的草稿”
“我当前的时区配置是什么？”
“将此电子邮件的附件保存到我的文档文件夹”
“将此报告转发给管理团队”

贡献

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

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

使用说明

Gmail MCP服务器

与其他用于电子邮件服务器的MCP有什么不同？

安装

选项1：使用NPX（推荐）

选项2：克隆并本地安装

设置Google Cloud OAuth凭据

与Claude一起使用

克劳德桌面

带有NPX的claude_desktop_config.json文件示例：

目的

项目结构

核心组件

配置

重要路径信息

特性

电子邮件操作

草案管理

高级功能

标签管理

时区支持

附件管理

可用工具

发送电子邮件

回复所有电子邮件

转发电子邮件

以帐户身份发送列表

获取最近的电子邮件

阅读电子邮件

搜索电子邮件

标签管理工具

列表标签

获取标签

创建标签

更新标签

删除标签

修改标签

邮件管理工具

标记为已读

标记为未读

存档邮件

已存档邮件

垃圾信息

草稿管理工具

创建草稿

获取草稿

列出草稿

更新草稿

删除草稿

发送草稿

时区工具

获取时区信息

附件管理工具

列出附件

保存附件

示例提示

贡献

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器