Gmail

gmail-mcp

用于 Gmail 的 MCP 服务，可读取、发送、归档和管理邮件。

使用场景

航班值机：“帮我办理明天航班的值机” → 查找你的确认邮件，提取预订编号，并通过浏览器办理值机。

费用报销：“把我上周在 Amazon 买的东西提交报销” → 查找收据，提取金额和类别，并在你的费用系统中提交报销。

包裹追踪：“Acme 寄来的包裹到哪了？” → 查找发货通知，提取追踪号码，并获取当前配送状态。

查找附件：“预算最后定了什么？Michelle 昨天发了我一些东西” → 定位邮件并打开附带的电子表格。

假期模式：“我 12 月 20 日到 1 月 2 日休假” → 一次性设置 Gmail 自动回复、屏蔽日历，并更新你的 Slack 状态。

会议后续跟进：通话结束后，你的助手会读取 Gemini 转录内容、总结关键决策，并起草包含待办事项的跟进邮件。

（这些只是一些示例——任何需要搜索、读取或发送邮件的工作流都可以使用此服务。）

设置

1. 创建 Google OAuth 凭据

1. 前往 Google Cloud Console
2. 创建新项目（或使用现有项目）
3. 启用 Gmail API
4. 前往 APIs & Services → OAuth consent screen，设置授权同意屏幕
5. 前往 APIs & Services → Credentials → Create Credentials → OAuth client ID
6. 选择 Web application
7. 将 http://localhost:3000/callback 添加到 Authorized redirect URIs
8. 记下你的 Client ID 和 Client Secret

2. 运行服务

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

服务默认运行在 http://localhost:3000。可通过 PORT=3001 更改端口。

3. 添加到你的 MCP 客户端

服务运行后，按照 install-mcp 上的说明操作，该页面会为你的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Cline、VS Code 等）生成相应的配置。

架构

此服务作为 Google 的 OAuth 代理：

graph LR
    A[MCP client] <--> B[gmail-mcp] <--> C[Google OAuth/API]

1. 服务通过 /.well-known/oauth-authorization-server 将自身声明为 OAuth 授权服务器
2. /register 返回 Google OAuth 客户端凭据
3. /authorize 重定向到 Google，并将客户端的回调 URL 编码到 state 中
4. /callback 接收 Google 返回的授权码，并转发给客户端的回调地址
5. /token 将令牌请求代理到 Google，并注入客户端凭据
6. /mcp 处理 MCP 请求，并使用 bearer token 调用 Gmail API

服务不保存令牌或状态，只代理发往 Google 的 OAuth 请求。

工具

工具	描述
gmail_get_profile	获取用户的电子邮件地址和个人资料信息
邮件
gmail_messages_list	搜索/列出邮件（建议改用 gmail_threads_list）
gmail_message_get	获取单封邮件
gmail_message_send	发送电子邮件
gmail_message_forward	将电子邮件转发给新收件人
gmail_message_modify	添加/移除标签
gmail_message_archive	归档（从收件箱中移除）
gmail_message_trash	移至垃圾箱
gmail_message_untrash	从垃圾箱恢复
gmail_message_delete	永久删除
gmail_messages_batch_modify	批量修改标签
gmail_messages_batch_delete	批量永久删除
邮件会话
gmail_threads_list	搜索/列出邮件会话（推荐）
gmail_thread_get	获取邮件会话中的所有邮件（推荐）
gmail_thread_modify	添加/移除标签
gmail_thread_trash	移至垃圾箱
gmail_thread_untrash	从垃圾箱恢复
gmail_thread_delete	永久删除
草稿
gmail_drafts_list	列出草稿
gmail_draft_get	获取草稿
gmail_draft_create	创建草稿
gmail_draft_update	更新草稿
gmail_draft_send	发送草稿
gmail_draft_delete	删除草稿
标签
gmail_labels_list	列出所有标签
gmail_label_get	获取标签
gmail_label_create	创建标签
gmail_label_update	更新标签
gmail_label_delete	删除标签
附件
gmail_attachment_get	下载附件
过滤器
gmail_filters_list	列出电子邮件过滤器
gmail_filter_get	获取过滤器
gmail_filter_create	创建过滤器
gmail_filter_delete	删除过滤器
设置
gmail_vacation_get	获取假期自动回复设置
gmail_vacation_set	设置假期自动回复

Gmail API 权限范围

• gmail.readonly - 读取邮件和标签
• gmail.send - 发送邮件
• gmail.modify - 修改邮件（归档、标签、移至垃圾箱）

贡献

欢迎在 GitHub 上提交拉取请求！开始贡献：

1. 安装 Git 和 Node.js
2. 克隆仓库
3. 使用 npm install 安装依赖项
4. 运行 npm run test 执行测试
5. 使用 npm run build 构建

发布

版本遵循语义化版本规范。

发布步骤：

1. 使用 npm version <major | minor | patch> 更新版本号
2. 运行 git push --follow-tags 推送并附带标签
3. 等待 GitHub Actions 发布到 NPM 注册表。