使用说明

Gmail MCP服务器

一个模型上下文协议（MCP）服务器，提供对Claude CLI的只读Gmail访问，支持基于标签的过滤和容器部署。

为什么使用这个？

安全第一：只读访问意味着克劳德无法发送、删除或修改您的电子邮件。标签过滤允许您限制哪些电子邮件可见。
总结重要信息：让克劳德阅读和总结电子邮件，这样你就可以快速理解什么是重要的。
永远不要错过重要的电子邮件：让克劳德搜索并突出显示收件箱中隐藏的关键信息，以避免被忽视。
节省时间：无需手动搜索数百封邮件，即可快速查找和理解电子邮件内容。

快速启动：

配置Claude CLI以信任您的证书（如果是自签名的）：
```
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```

添加服务器：

claude mcp add --transport http gmail https://localhost:3000/mcp?allowed_labels=INBOX

然后问克劳德： “总结我今天未读的电子邮件” 或 “查找有关项目截止日期的所有电子邮件”

专业提示： 为频繁的任务创建自定义斜线命令。添加到 .claude/commands/email-summary.md:

Summarize unread emails from last 24 hours. Group by sender and highlight action items.

然后使用 /email-summary 任何时候。

Claude CLI集成

证书配置

对于自签名或内部CA证书，请配置Claude CLI以信任它们：

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

或者，添加到 ~/.claude/settings.json:

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/path/to/ca-cert.pem"
  }
}

注：这 settings.json 由于潜在的Claude CLI错误，可能无法应用env配置。如果遇到证书错误，请改用shell环境变量方法。

通过命令行添加服务器

claude mcp add --transport http gmail https://localhost:3001/mcp?allowed_labels=INBOX,STARRED

通过URL进行标签筛选： 使用配置Claude可以访问哪些Gmail标签 allowed_labels 查询参数。使用逗号分隔的标签名称（例如。， INBOX,STARRED,IMPORTANT).此参数是必需的。

手动配置

Claude CLI配置存储在 ~/.claude.json:

{
  "mcpServers": {
    "gmail": {
      "transport": "http",
      "url": "https://localhost:3001/mcp?allowed_labels=INBOX,STARRED"
    }
  }
}

集成步骤

确保服务正在运行：
```
curl http://localhost:3001/health
```
预期响应： {"status":"ok"}
添加服务器 （见上文）
身份验证：
- 启动克劳德代码： claude
- 跑 /mcp 命令
- 选择gmail服务器
- 选择“身份验证”
- 在浏览器中完成Google OAuth
验证工具是否可用： 问克劳德：“你有什么Gmail工具？”

Claude应该列出三个Gmail工具：
- list_messages
- read_message
- search_messages

可用工具

1.列表消息

列出按允许的标签筛选的Gmail邮件。

参数：

maxResults （number，可选）：要返回的最大消息数（默认值：10）
pageToken （字符串，可选）：分页的页面标记

退货：

消息摘要数组，包含：
- id：消息ID
- threadId：线程ID
- snippet：消息预览
- labelIds：标签ID数组
- from：发件人电子邮件地址
- subject：电子邮件主题
- date：发送日期

2.read_message

读取特定消息的完整内容。

参数：

messageId （string，必填）：要读取的消息的ID
maxSize （数字，可选）：以字符为单位的最大正文大小。如果超过此值，则主体将被截断。

退货：

完整消息对象包含：
- id：消息ID
- threadId：线程ID
- labelIds：标签ID数组
- from：发件人电子邮件地址
- to：收件人电子邮件地址
- subject：电子邮件主题
- date：发送日期
- body：完整的电子邮件正文（Markdown格式）
- bodySize：原始机身尺寸（字符）
- truncated：主体是否被截断
- snippet：消息预览

注：此工具在返回内容之前验证消息是否至少有一个允许的标签。纯HTML电子邮件会自动转换为Markdown，以提高可读性和令牌效率。

3.搜索消息

使用Gmail查询语法搜索邮件。

参数：

query （字符串，必填）：Gmail搜索查询（例如，“发件人：example@gmail.com主题：发票”）
maxResults （number，可选）：要返回的最大消息数（默认值：10）
pageToken （字符串，可选）：分页的页面标记

退货：

匹配的消息摘要数组（格式与 list_messages)

注：标签过滤会自动应用于搜索结果。

用法示例

示例1：列出最近的电子邮件

User: List my 5 most recent Gmail messages

Claude: [Uses list_messages tool with maxResults: 5]

Claude将返回一个包含5条消息的列表，显示ID、主题、发件人和日期。

示例2：阅读特定消息

User: Read the full content of message ID 18c2f4a3b5e91234

Claude: [Uses read_message tool with messageId: "18c2f4a3b5e91234"]

Claude将返回完整的电子邮件内容，包括邮件头和正文。

示例3：搜索电子邮件

User: Search my Gmail for emails from support@example.com

Claude: [Uses search_messages tool with query: "from:support@example.com"]

Claude将返回来自该发件人的所有匹配消息（按允许的标签筛选）。

示例4：复杂搜索

User: Find emails from last week with "invoice" in the subject

Claude: [Uses search_messages with query: "after:2025/11/23 subject:invoice"]

Claude将使用Gmail的搜索语法返回匹配的邮件。

标签筛选

标签过滤允许您通过指定允许标签的白名单来控制Claude可以访问哪些电子邮件。

配置

标签过滤是通过MCP服务器URL查询参数为每个用户配置的 allowed_labels:

claude mcp add --transport http gmail http://localhost:3001/mcp?allowed_labels=INBOX,STARRED

或者在Claude CLI配置中：

{
  "mcpServers": {
    "gmail": {
      "transport": "http",
      "url": "http://localhost:3001/mcp?allowed_labels=INBOX,STARRED"
    }
  }
}

标签ID格式

系统标签 （大写）：

INBOX -收件箱
SENT -已发送邮件
DRAFT -草稿
TRASH -垃圾桶
SPAM -垃圾邮件
IMPORTANT -重要事项
STARRED -主演
UNREAD -未读

类别标签:

CATEGORY_PERSONAL
CATEGORY_SOCIAL
CATEGORY_PROMOTIONS
CATEGORY_UPDATES
CATEGORY_FORUMS

自定义标签: 直接使用您的自定义标签名称（例如。， Work, Personal).服务器会自动将名称解析为ID。

过滤是如何工作的

标签过滤应用于三个级别：

list_消息：仅返回至少有一个允许标签的邮件
read_message：在返回内容之前，验证邮件是否具有允许的标签
搜索消息：自动将标签筛选器添加到搜索查询中

这 allowed_labels 参数是必需的 /mcp 终点。如果为空或缺失，则返回400错误。

例子

只允许收件箱和星号：

http://localhost:3001/mcp?allowed_labels=INBOX,STARRED

允许收件箱和自定义标签：

http://localhost:3001/mcp?allowed_labels=INBOX,Work

允许与工作相关的类别：

http://localhost:3001/mcp?allowed_labels=INBOX,IMPORTANT,CATEGORY_UPDATES

更新标签

更改 allowed_labels，更新Claude CLI配置中的URL：

选项1：编辑配置文件

编辑 ~/.claude.json 并修改URL：

{
  "mcpServers": {
    "gmail": {
      "url": "https://localhost:3001/mcp?allowed_labels=INBOX,NEW_LABEL"
    }
  }
}

选项2：删除并重新添加服务器

claude mcp remove gmail
claude mcp add --transport http gmail https://localhost:3001/mcp?allowed_labels=INBOX,NEW_LABEL

故障排除

常见问题

“未通过身份验证”错误：

解决方案： 通过Claude CLI重新进行身份验证：

跑 /mcp 克劳德代码中的命令
选择gmail服务器
选择“身份验证”
在浏览器中完成Google OAuth

“403禁止”错误：

解决方案： 检查您是否已启用Gmail API并配置了正确的OAuth范围(gmail.readonly).

“超出配额”错误：

解决方案： 在谷歌云控制台中检查你的Gmail API使用情况：

首选https://console.cloud.google.com
选择您的项目
导航到“API和服务”>“仪表板”
检查Gmail API配额

默认配额为每天10亿单位，这应该足以供个人使用。

“连接被拒绝”错误：

解决方案： 验证服务是否正在运行：

curl http://localhost:3000/health

令牌无效时出现“超时”错误：

当MCP服务器返回401（令牌解密失败或刷新令牌被撤销）时，Claude CLI可能会报告超时而不是身份验证错误。

解决方案： 通过Claude CLI重新进行身份验证：

跑 /mcp 克劳德代码中的命令
选择gmail服务器
选择“身份验证”
在浏览器中完成Google OAuth

未出现在Claude CLI中的工具：

解决方案：

验证config.json格式是否正确
检查URL是否可访问： curl http://localhost:3000/health
重新启动Claude CLI
检查Claude CLI日志是否有错误

服务器管理

以下部分适用于部署和管理MCP服务器的管理员。

特性

无状态架构 -无服务器端会话存储的加密承载令牌（JWE）
多租户OAuth 2.0 -多个拥有独立Gmail帐户的客户端
服务器端Google回调 -谷歌重定向到服务器，而不是直接重定向到客户端
按用户标签过滤 -每个用户配置自己的允许标签
透明令牌刷新 -每次请求时自动刷新Google令牌
三个MCP工具：列出邮件、阅读邮件内容、搜索邮件
结构化日志记录 -生产中具有JSON输出的Pino记录器
单元测试 -Vitest认证模块测试套件
HTTPS传输 用于安全的远程部署
Docker就绪 进行健康检查

建筑

服务器使用无状态架构，其中Google OAuth令牌被加密为返回给Claude CLI的JWE（JSON Web加密）承载令牌。在每次请求时，服务器都会解密令牌，如果过期，则刷新Google访问令牌，并执行Gmail API调用。

有三种MCP工具可供选择：

list_messages：列出按允许标签筛选的Gmail邮件
read_message：阅读特定消息的完整内容
search_messages：使用Gmail查询语法搜索邮件

所有通信都通过HTTPS进行。凭据和加密密钥从通过环境变量指定的文件中加载。

先决条件

Node.js >= 22.0.0
码头工人 （用于集装箱化部署）
Gmail帐户
谷歌云控制台 帐户（免费级别足够）
Claude CLI 安装

谷歌云控制台设置

第一步：创建谷歌云项目

引导到https://console.cloud.google.com
单击顶部导航栏中的项目下拉列表
点击“新建项目”
输入项目名称：“Gmail MCP服务器”（或您喜欢的任何名称）
注意项目ID（必须是全局唯一的）
点击“创建”

备注：免费套餐足以供个人使用。

步骤2：启用Gmail API

在谷歌云控制台中，确保您的项目已被选中
导航到“API和服务”>“库”（左侧边栏）
搜索“Gmail API”
点击结果中的“Gmail API”
点击“启用”按钮
等待API启用（约30秒）

备注：启用API不需要任何成本；它采用按使用付费定价。

步骤3：配置OAuth同意屏幕

导航到“API和服务”>“OAuth同意屏幕”
选择用户类型：
- 如果使用个人Gmail帐户，请选择“外部”
- 如果使用谷歌工作区，请选择“内部”
点击“创建”
填写应用程序信息：
- 应用程序名称：“Gmail MCP服务器”
- 用户支持电子邮件：您的电子邮件地址
- 开发者联系人：您的电子邮件地址
点击“保存并继续”
添加作用域：
- 点击“添加或删除范围”
- 搜索“gmail.readonly”
- 勾选以下框： https://www.googleapis.com/auth/gmail.readonly
- 点击“更新”
点击“保存并继续”
添加测试用户：
- 点击“添加用户”
- 输入您的Gmail地址
- 点击“添加”
点击“保存并继续”
查看摘要并单击“返回仪表板”

重要：只读作用域(gmail.readonly)是最安全的选择，也是所需的一切。

步骤4：创建OAuth 2.0凭据

导航到“API和服务”>“凭据”
点击“创建凭据”>“OAuth客户端ID”
如果系统提示配置同意屏幕，则应该已经完成了
应用程序类型：选择 “Web应用程序”
名称：“Gmail MCP服务器”
添加授权重定向URI：可访问MCP服务器回调端点的URL
- 这必须是用户登录谷歌后从浏览器可访问的实际URL
- 生产： https://mcp.example.com/callback
- 本地测试： http://localhost:3000/callback
点击“创建”
点击“下载JSON”下载凭据文件
将文件另存为 credentials.json 在你的 credentials/ 目录

重要:

凭据中的重定向URI必须与Google Cloud Console中配置的完全匹配
确保凭据安全，永远不要将其提交给版本控制

下载的文件格式：

{
  "web": {
    "client_id": "xxx.apps.googleusercontent.com",
    "client_secret": "xxx",
    "redirect_uris": ["https://mcp.example.com/callback"]
  }
}

对于Docker部署，将此文件作为卷挂载或使用容器机密。

安装和设置

克隆或下载

如果您在本地有此项目，请导航到项目目录：

cd /path/to/email-mcp

安装依赖项

npm install

身份验证流程（MCP OAuth 2.1）

服务器实现 MCP授权规范使用OAuth 2.1和PKCE。这创建了一个两层OAuth流：Claude CLI通过Gmail MCP服务器进行身份验证，而Gmail MCP服务器又通过Google进行身份验证。

┌─────────────┐     ┌─────────────────┐     ┌────────────────┐
│ Claude CLI  │────▶│ Gmail MCP Server│────▶│  Google OAuth  │
└─────────────┘     └─────────────────┘     └────────────────┘
   MCP OAuth 2.1         Proxies to           Google OAuth 2.0
   with PKCE            Google OAuth

分步流程

1.发现和客户注册

Claude CLI发现服务器的OAuth功能：

获取 /.well-known/oauth-authorization-server 用于OAuth元数据
获取 /.well-known/oauth-protected-resource 用于资源元数据
在执行动态客户端注册 /register （RFC 7591）

2.授权请求（Claude CLI→ 服务器→ 浏览器）

Claude CLI使用PKCE启动OAuth 2.1：

Claude CLI打开浏览器 /authorize 和 code_challenge
服务器存储挂起的请求（客户端ID、重定向URI、代码质询）
服务器通过HTTP 302重定向到Google OAuth进行响应（浏览器自动跟随）

3.谷歌身份验证（浏览器→ 谷歌→ 服务器→ 浏览器）

用户通过谷歌进行身份验证：

用户登录并授权 gmail.readonly 许可
谷歌以HTTP 302重定向响应 /callback （浏览器如下）
服务器将Google授权码交换为Google访问/刷新令牌
服务器生成MCP授权码
服务器通过HTTP 302重定向到Claude CLI回调进行响应（浏览器如下）

4.代币交换（Claude CLI→ 服务器）

Claude CLI完成OAuth流程：

将MCP授权码兑换为访问令牌 /token
服务器验证PKCE code_verifier 使用SHA-256对存储 code_challenge
服务器将Google令牌+用户电子邮件加密为JWE（JSON Web加密）令牌
服务器将加密的JWE作为MCP承载令牌返回

5.经过身份验证的MCP请求（无状态）

Claude CLI使用承载令牌：

向发送请求 /mcp?allowed_labels=... 和 Authorization: Bearer <encrypted-jwe>
服务器解密JWE以提取Google令牌
如果过期，服务器将刷新Google访问令牌（对客户端透明）
服务器执行Gmail API调用并返回结果

Claude CLI身份验证

最简单的身份验证方法是使用Claude CLI内置的OAuth支持：

将服务器添加到Claude CLI：

claude mcp add --transport http gmail https://localhost:3000/mcp?allowed_labels=INBOX

在Claude Code中，运行：
```
/mcp
```
选择gmail服务器并选择“身份验证”
在浏览器中完成Google OAuth流程

Claude CLI自动处理令牌存储和刷新。

快速启动（地方发展）

对于本地开发和测试：

1.建设项目

npm run build

2.启动服务器

npm start

服务器将在端口3000（或 PORT 环境变量）。

3.测试服务器

健康检查：

curl http://localhost:3000/health

预期响应：

{"status":"ok"}

测试MCP工具列表：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

您应该看到列出了四个工具： list_messages, read_message, search_messages, logout.

4.发展模式

对于自动重新加载的开发：

npm run dev

环境变量

变量	必填	默认	描述
`OAUTH_CREDENTIALS_PATH`	是	-	谷歌OAuth凭据JSON文件的路径
`TOKEN_ENCRYPTION_PATH`	是	-	包含32字节加密密钥（十六进制或base64）的文件路径
`TLS_KEY_PATH`	是	-	TLS私钥文件（PEM）的路径
`TLS_CERT_PATH`	是	-	TLS证书文件（PEM）的路径
`PORT`	无	3000	HTTPS服务器端口
`HOST`	否	localhost	服务器主机名
`SESSION_TTL`	无	86400	MCP会话TTL（秒）（默认值：24小时）
`LOG_LEVEL`	无	信息	日志级别（跟踪、调试、信息、警告、错误、致命）
`NODE_ENV`	否	-	设置为JSON日志输出的“生产”

注：通过URL查询参数为每个客户端配置标签筛选 allowed_labels。此参数是必需的，不能为空。

安全考虑

OAuth作用域

此服务器使用 gmail.readonly 范围，其中规定：

只读访问 到Gmail邮件和元数据
没有能力 发送、删除或修改电子邮件
无权限 转到Gmail设置或帐户信息

这是访问Gmail数据最安全的范围。

凭据存储

地方发展：

凭据存储在 credentials/ 目录
目录通过从git中排除 .gitignore
永不承诺 credentials/ 到版本控制

容器部署：

使用容器机密或装载的卷作为凭据
确保凭据文件是只读的
使用环境变量进行配置

许可证管理

MCP承载令牌 是一个加密的JWE，包含Google令牌和用户电子邮件
无状态设计：服务器没有用于经过身份验证的请求的持久存储
谷歌访问令牌 1小时后过期（每次请求时自动透明刷新）
谷歌刷新令牌 长期有效（直到用户手动撤销）
加密密钥 是必需的(TOKEN_ENCRYPTION_PATH)-按键旋转使所有令牌无效
需要重新身份验证 何时：刷新令牌被撤销、加密密钥被旋转或令牌损坏

OAuth安全措施

服务器实现了几个OAuth 2.1安全措施：

PKCE S256验证：使用SHA-256哈希比较验证代码验证器
重定向URI验证：授权期间只接受注册的重定向URI
加密的承载令牌：JWE令牌使用AES-256-GCM加密（dir/A256GCM）
状态参数验证：OAuth状态使用严格解析的UUID格式
授权码一次性使用：代码在交换后立即删除

最佳实践

永远不要泄露秘密：确保 credentials/ 在...里 .gitignore
使用Docker秘密：始终在生产部署中使用机密
定期旋转令牌：定期重新生成OAuth令牌
限制网络暴露：限制对localhost的访问或使用HTTPS反向代理
监控API配额：查看Google云控制台以了解Gmail API的使用情况
使用TLS：使用HTTPS在反向代理后部署以进行远程访问
审核访问权限：查看您的Google帐户中的OAuth同意屏幕和授权应用程序

Gmail API配额

默认配额： 每天10亿单位
个人使用应保持在限制范围内
监控Google Cloud控制台中的使用情况
服务器不实施额外的速率限制

发展

地方发展设置

安装依赖项：
```
npm install
```
在开发模式下运行（自动重新加载）：
```
npm run dev
```
首次访问服务器时通过Claude CLI进行身份验证

运行测试

运行单元测试：

npm test

在监视模式下运行测试：

npm run test:watch

运行覆盖率测试：

npm run test:coverage

建筑

构建项目：

npm run build

测试编译后的输出：

npm start

做出改变

修改源文件 src/
使用运行测试 npm test
本地测试 npm run dev
建立 npm run build
重建Docker镜像并重新部署

许可和贡献

该项目根据 MIT许可证.

贡献

欢迎投稿！拜托：

克隆该仓库
创建要素分支
进行更改
提交拉取请求

支持

对于问题或疑问：

检查服务日志： docker service logs gmail-mcp
验证机密： docker secret ls
测试健康终点： curl http://localhost:3000/health
在Google云控制台中检查Gmail API配额
通过在本地重新生成来验证令牌的有效性

使用说明

Gmail MCP服务器

为什么使用这个？

Claude CLI集成

证书配置

通过命令行添加服务器

手动配置

集成步骤

可用工具

1.列表消息

2.read_message

3.搜索消息

用法示例

示例1：列出最近的电子邮件

示例2：阅读特定消息

示例3：搜索电子邮件

示例4：复杂搜索

标签筛选

配置

标签ID格式

过滤是如何工作的

例子

更新标签

故障排除

常见问题

服务器管理

特性

建筑

先决条件

谷歌云控制台设置

第一步：创建谷歌云项目

步骤2：启用Gmail API

步骤3：配置OAuth同意屏幕

步骤4：创建OAuth 2.0凭据

安装和设置

克隆或下载

安装依赖项

身份验证流程（MCP OAuth 2.1）

分步流程

Claude CLI身份验证

快速启动（地方发展）

1.建设项目

2.启动服务器

3.测试服务器

4.发展模式

环境变量

安全考虑

OAuth作用域

凭据存储

许可证管理

OAuth安全措施

最佳实践

Gmail API配额

发展

地方发展设置

运行测试

建筑

做出改变

许可和贡献

贡献

支持

相关 MCP

邮件过滤管理服务

邮件摘要服务

邮件摘要工具

IMAP邮件管理服务器

日历与邮件管理MCP服务

Gmail邮件处理服务