faithk7-gmail-mcp

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

功能

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

前置条件

依赖项

最简单的安装方式是安装 Node.js 18+。如果要在本地构建，还需要安装 pnpm。

Google Workspace 设置

要运行此 MCP 服务，需要为组织设置 Google API 客户端，并让每位用户运行脚本来获取自己的 OAuth 刷新令牌。

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

1. 前往 Google Cloud Console。
2. 创建新项目或选择现有项目。
3. 为项目启用 Gmail API。
4. 前往 Credentials 并创建 OAuth 2.0 Client ID。客户端类型选择“Desktop app”。
5. 下载 OAuth 密钥 JSON，并保存为 ~/.gmail-mcp/gcp-oauth.keys.json。⚠️ 注意：要通过 MacOS 的 Finder 应用创建 ~/.gmail-mcp/，需要先显示隐藏文件。
6. （可选）如需安装远程服务（例如使用 Smithery CLI），请记下此文件中的 CLIENT_ID 和 CLIENT_SECRET。

客户端 OAuth 设置（每位用户一次）

1. 让用户将 ~/.gmail-mcp/gcp-oauth.keys.json 复制到自己电脑上的相同路径。
2. 运行 npx @shinzolabs/gmail-mcp auth。
3. 系统会打开浏览器窗口，用户可以选择个人资料、查看请求的权限范围并批准。
4. （可选）如需安装远程服务，请记下成功消息中提及的文件路径（默认为 ~/.gmail-mcp/credentials.json）。用户的 REFRESH_TOKEN 可在此文件中找到。

客户端配置

配置 MCP 客户端以连接此服务有多种方式。对于托管或远程服务设置，请使用 Smithery CLI 和 Smithery API Key。对于本地安装，请使用 npx 或从源代码构建。以下将逐一介绍这些选项。

Smithery 远程服务（推荐）

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

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

根据提示输入 CLIENT_ID、CLIENT_SECRET 和 REFRESH_TOKEN。

Smithery SDK

如果你正在开发自己的 Agent 应用，可以使用这里的样板代码。

NPX 本地安装

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

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

从源代码构建

1. 下载仓库：

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

2. 在克隆的仓库中使用 pnpm 安装软件包并构建：

pnpm i && pnpm build

3. 将以下内容添加到 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	Streamable HTTP 传输方式的端口	否	3000
TELEMETRY_ENABLED	启用遥测	否	true

支持的端点

用户管理

• 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，了解问题反馈、贡献方式和联系信息的相关指南。

数据收集与隐私

Shinzo Labs 会从此服务收集有限的匿名遥测数据，以帮助改进我们的产品和服务。此过程中不会收集任何个人身份信息。请查看 Privacy Policy，详细了解收集的数据类型以及如何选择退出此遥测数据收集。

许可证

MIT