Gmail MCP

一个为 Gmail API 实现的 模型上下文协议 (MCP)，提供了一个用于电子邮件管理、发送和检索的标准化接口。

特性

• 完整的 Gmail API 覆盖，包括消息、线程、标签、草稿和设置
• 支持发送、起草和管理电子邮件
• 标签管理，具有可自定义的颜色和可见性设置
• 用于会话管理的线程操作
• 设置管理，包括休假回复、IMAP/POP 和语言设置
• 用于邮箱更改的历史记录跟踪
• 使用您的 Google Cloud 凭据进行安全的 OAuth2 身份验证

安装

⚠️ 注意： 由于此服务器上提供了大量的端点，建议您安装并设置 Heimdall 以限制暴露给您的客户端应用程序的端点数量。

要使用此 MCP，您需要设置 Gmail 的身份验证：

1. 转到 Google Cloud Console
2. 创建一个新项目或选择一个现有项目
3. 为您的项目启用 Gmail API
4. 转到“凭据”并创建一个 OAuth 2.0 客户端 ID
   • 选择“桌面应用”作为应用程序类型（警告：如果您不选择此类型，服务器将无法解析 JSON 文件中的密钥）
   • 下载客户端凭据 JSON 文件
5. 将下载的凭据文件保存到 ~/.gmail-mcp/gcp-oauth.keys.json

NPX (推荐)

将以下内容添加到您的 MCP 客户端 config.json 中（如果使用 Heimdall，则为 ~/.heimdall/config.json）：

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

手动下载

1. 下载仓库：

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

2. 安装包并构建（在克隆的仓库中）：

pnpm i && pnpm run build

3. 将以下内容添加到您的 MCP 客户端 config.json 中（如果使用 Heimdall，则为 ~/.heimdall/config.json）：

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

Smithery

要通过 Smithery 为 Claude Desktop 自动安装：

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

身份验证

自动 (推荐)

此 MCP 提供自动身份验证流程：

1. 首先，获取 OAuth 凭据并下载 JSON 文件。

2. 将 JSON 文件重命名为 gcp-oauth.keys.json 并将其复制到 $HOME/.gmail-mcp/，或者您在 MCP_CONFIG_DIR 中设置的任何位置。

3. 运行身份验证命令：

# 如果使用 npx
npx @shinzolabs/gmail-mcp auth

# 如果在项目目录中
pnpm i && pnpm run build && pnpm run auth

4. 将自动打开一个浏览器窗口，显示 Google OAuth 同意屏幕
5. 授予访问权限后，您可以关闭浏览器窗口
6. 令牌将自动保存到 $HOME/.gmail-mcp/credentials.json

MCP 将自动执行以下操作：

• 管理令牌刷新
• 将凭据保存到磁盘
• 处理 OAuth 回调
• 在您的默认浏览器中打开身份验证 URL

注意：默认情况下，此服务器使用端口 3000 来侦听 OAuth 响应。 如果您在 3000 上运行其他服务，则可以将 AUTH_SERVER_PORT 设置为其他值。

您可以通过在运行命令之前设置 MCP_CONFIG_DIR 来自定义配置位置（可选）：

export MCP_CONFIG_DIR=/custom/path/to/directory/

手动 (建议用于 Docker 使用)

如果您愿意，您也可以直接通过环境变量提供凭据：

export CLIENT_ID=your-id
export CLIENT_SECRET=your-secret
export REFRESH_TOKEN=your-refresh-token

支持的端点

用户管理

• 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 配置

贡献

欢迎并鼓励贡献。如有任何问题、意见或疑虑，请联系 austin@shinzolabs.com。