Gmail MCP

一个为 Gmail API 实现的 Model Context Protocol (MCP)，提供了标准化的接口用于邮件管理、发送和检索。

功能

完整的 Gmail API 覆盖，包括消息、线程、标签、草稿和设置
支持发送、起草和管理邮件
标签管理，支持自定义颜色和可见性设置
线程操作，用于管理对话
设置管理，包括假期回复、IMAP/POP 和语言设置
邮箱变更的历史跟踪
使用 Google Cloud 凭证进行安全的 OAuth2 认证

先决条件

要运行此 MCP 服务器，首先需要为您的组织设置 Google API 客户端，每个用户需要运行一个脚本来获取自己的 OAuth 刷新令牌。

Google API 客户端设置（每个组织一次）

前往 Google Cloud Console。
创建一个新项目或选择一个现有项目。
为您的项目启用 Gmail API。
前往“凭证”并创建一个 OAuth 2.0 客户端 ID。选择“桌面应用”作为客户端类型。
下载并保存 OAuth 密钥 JSON 文件为 ~/.gmail-mcp/gcp-oauth.keys.json。⚠️ 注意：要通过 MacOS 的 Finder 应用创建 ~/.gmail-mcp/，您需要先启用隐藏文件。
（可选）对于远程服务器安装（例如使用 Smithery CLI），请记下此文件中的 CLIENT_ID 和 CLIENT_SECRET。

客户端 OAuth（每个用户一次）

让用户将 ~/.gmail-mcp/gcp-oauth.keys.json 复制到他们的计算机上的相同路径。
运行 npx @shinzolabs/gmail-mcp auth。
将打开一个浏览器窗口，用户可以在其中选择一个配置文件，查看请求的范围并批准。
（可选）对于远程服务器安装，请记下成功消息中提到的文件路径（默认为 ~/.gmail-mcp/credentials.json）。用户的 REFRESH_TOKEN 将在此处找到。

客户端配置

有几种方法可以将您的 MCP 客户端配置为与服务器连接。对于托管/远程服务器设置，请使用 Smithery 的 CLI 和 Smithery API 密钥。对于本地安装，请使用 npx 或从源代码构建。以下将解释这些选项。

Smithery 远程服务器（推荐）

要将远程服务器添加到您的 MCP 客户端 config.json 中，请从 Smithery CLI 运行以下命令：

npx -y @smithery/cli install @shinzo-labs/gmail-mcp

在提示时输入您的 CLIENT_ID、CLIENT_SECRET 和 REFRESH_TOKEN。

Smithery SDK

如果您正在开发自己的代理应用程序，可以使用此处的样板代码。

NPX 本地安装

要使用 npx 本地安装服务器，请将以下内容添加到您的 MCP 客户端 config.json 中：

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@shinzolabs/gmail-mcp"
      ]
    }
  }
}

从源代码构建

下载仓库：

git clone https://github.com/shinzo-labs/gmail-mcp.git

安装包并使用 pnpm 构建（在克隆的仓库内）：

pnpm i && pnpm build

将以下内容添加到您的 MCP 客户端 config.json 中：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/path/to/gmail-mcp/dist/index.js"
      ]
    }
  }
}

配置变量

变量	描述	是否必需	默认值
`AUTH_SERVER_PORT`	临时 OAuth 认证服务器的端口	否	`3000`
`CLIENT_ID`	Google API 客户端 ID（在 `GMAIL_OAUTH_PATH` 中找到）	如果是远程服务器连接则为是	`''`
`CLIENT_SECRET`	Google API 客户端密钥（在 `GMAIL_OAUTH_PATH` 中找到）	如果是远程服务器连接则为是	`''`
`GMAIL_CREDENTIALS_PATH`	用户凭证文件的路径	否	`MCP_CONFIG_DIR/credentials.json`
`GMAIL_OAUTH_PATH`	Google API 客户端文件的路径	否	`MCP_CONFIG_DIR/gcp-oauth.keys.json`
`MCP_CONFIG_DIR`	存储配置文件的目录	否	`~/.gmail-mcp`
`REFRESH_TOKEN`	OAuth 刷新令牌（在 `GMAIL_CREDENTIALS_PATH` 中找到）	如果是远程服务器连接则为是	`''`
`PORT`	可流式 HTTP 传输方法的端口	否	`3000`

支持的端点

用户管理

get_profile: 获取当前用户的 Gmail 个人资料
stop_mail_watch: 停止接收推送通知
watch_mailbox: 设置邮箱变更的推送通知

消息管理

管理消息

list_messages: 列出消息，支持可选过滤
get_message: 获取特定消息
get_attachment: 获取消息附件
modify_message: 修改消息标签
send_message: 发送邮件到指定收件人
delete_message: 永久删除消息
trash_message: 将消息移至垃圾箱
untrash_message: 将消息从垃圾箱中移除
batch_modify_messages: 批量修改消息
batch_delete_messages: 批量删除消息

标签管理

list_labels: 列出所有标签
get_label: 获取特定标签
create_label: 创建新标签
update_label: 更新标签
patch_label: 部分更新标签
delete_label: 删除标签

线程管理

list_threads: 列出邮件线程
get_thread: 获取特定线程
modify_thread: 修改线程标签
trash_thread: 将线程移至垃圾箱
untrash_thread: 将线程从垃圾箱中移除
delete_thread: 删除线程

草稿管理

list_drafts: 列出用户邮箱中的草稿
get_draft: 通过 ID 获取特定草稿
create_draft: 在 Gmail 中创建草稿邮件
update_draft: 替换草稿内容
delete_draft: 删除草稿
send_draft: 发送现有草稿

设置管理

自动转发

get_auto_forwarding: 获取自动转发设置
update_auto_forwarding: 更新自动转发设置

IMAP 设置

get_imap: 获取 IMAP 设置
update_imap: 更新 IMAP 设置

POP 设置

get_pop: 获取 POP 设置
update_pop: 更新 POP 设置

假期回复

get_vacation: 获取假期回复设置
update_vacation: 更新假期回复

语言设置

get_language: 获取语言设置
update_language: 更新语言设置

委托

list_delegates: 列出账户委托
get_delegate: 获取特定委托
add_delegate: 添加委托
remove_delegate: 移除委托

过滤器

list_filters: 列出邮件过滤器
get_filter: 获取特定过滤器
create_filter: 创建新过滤器
delete_filter: 删除过滤器

转发地址

list_forwarding_addresses: 列出转发地址
get_forwarding_address: 获取特定转发地址
create_forwarding_address: 创建转发地址
delete_forwarding_address: 删除转发地址

发送为设置

list_send_as: 列出发送为别名
get_send_as: 获取特定发送为别名
create_send_as: 创建发送为别名
update_send_as: 更新发送为别名
patch_send_as: 部分更新发送为别名
verify_send_as: 发送验证邮件
delete_send_as: 删除发送为别名

S/MIME 设置

list_smime_info: 列出 S/MIME 配置
get_smime_info: 获取特定 S/MIME 配置
insert_smime_info: 上传新的 S/MIME 配置
set_default_smime_info: 设置默认 S/MIME 配置
delete_smime_info: 删除 S/MIME 配置

贡献

欢迎并鼓励贡献！请阅读 CONTRIBUTING.md 了解问题、贡献和联系信息的指南。