Gmail MCP Server 实战指南：让 AI Agent 安全、可靠地收发与管理 Gmail 邮件

Gmail MCP Server 实战指南：让 AI Agent 安全、可靠地收发与管理 Gmail 邮件

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

本文是 Klavis 开源仓库中 Gmail MCP Server（mcp_servers/gmail）的完整技术指南。它以 Model Context Protocol（MCP）协议封装 Gmail 与 Google People API，为 AI Agent 提供读邮件、发邮件、管理标签、批量操作、附件解析与联系人检索等能力，并内置完整的 OAuth 认证支持。读完本文，你将掌握该服务器的全部工具与参数、两种认证方式（托管 OAuth 与手动 Token）的配置方法、Docker 自托管与本地源码构建流程，并能结合源码理解其底层实现原理。

一、项目定位与核心能力

Gmail MCP Server 是一个基于 Node.js/TypeScript 构建的 MCP 服务器，通过 Gmail API 实现邮件的读取、发送与管理，并通过 People API 实现联系人检索。它对外暴露标准 MCP 工具接口，可被任何 MCP 兼容客户端（Claude Desktop、Cursor、VS Code 等）直接调用。

从源码看，服务器实现位于 mcp_servers/gmail/src/index.ts，使用@modelcontextprotocol/sdk构建 MCP Server 实例，并用googleapis初始化 Gmail v1 与 People v1 客户端；依赖清单见 mcp_servers/gmail/package.json（包括pdfjs-dist、mammoth、exceljs等附件解析库）。

核心能力可归纳为四类：

能力域	说明	对应工具
邮件读取	拉取邮件、按 Gmail 搜索语法检索、获取邮件详情	gmail_read_email、gmail_search_emails
邮件发送	发送新邮件（含富文本/HTML、抄送密送、回复线程）	gmail_send_email、gmail_draft_email
邮件管理	标记已读/未读、归档、删除，以及批量操作	gmail_modify_email、gmail_delete_email、gmail_batch_modify_emails、gmail_batch_delete_emails
附件与联系人	下载并解析附件内容、按姓名/邮箱/电话检索联系人	gmail_get_email_attachments、gmail_search_contacts

二、快速开始：30 秒跑通

2.1 使用 Klavis 托管服务（推荐生产环境）

无需自行搭建基础设施，安装官方 SDK 后即可创建 Gmail 实例：

pip install klavis # 或 npm install klavis

from klavis import Klavis klavis = Klavis(api_key="your-free-key") server = klavis.mcp_server.create_server_instance("GMAIL", "user123")

托管模式下，Gmail 的 OAuth 认证流由 Klavis 平台自动托管，无需接触 Token 细节。

2.2 使用 Docker 自托管

拉取官方镜像并按需选择认证方式：

# 拉取最新镜像 docker pull ghcr.io/klavis-ai/gmail-mcp-server:latest # 方式一：通过 Klavis AI 托管 OAuth（推荐） docker run -p 5000:5000 -e KLAVIS_API_KEY=$KLAVIS_API_KEY \ ghcr.io/klavis-ai/gmail-mcp-server:latest # 方式二：手动提供 Gmail access token（不依赖 OAuth 流程） docker run -p 5000:5000 -e AUTH_DATA='{"access_token":"your_gmail_access_token_here"}' \ ghcr.io/klavis-ai/gmail-mcp-server:latest

容器默认监听 5000 端口。镜像构建方式可参考 mcp_servers/gmail/Dockerfile：先以node:22-alpine执行npm run build编译 TypeScript，再以node:22-slim作为运行镜像并执行node build/src/index.js。

OAuth 说明：Gmail 强制要求 OAuth 认证。使用KLAVIS_API_KEY时，OAuth 流程由 Klavis 自动处理；使用AUTH_DATA时则需自行提供有效的 Gmail access token。

三、认证机制详解：三种凭证注入方式

服务器运行时会从请求中提取 Gmail access token，认证优先级与实现位于 mcp_servers/gmail/src/index.ts：

1. 环境变量AUTH_DATA：JSON 字符串，需包含access_token字段，如{"access_token":"ya29.xxx"}；
2. 请求头x-auth-data：对同样的 JSON 做 Base64 编码后放入该请求头，服务器会解码并解析出access_token，适合多租户场景下按请求注入不同凭证；
3. 两者都未提供时，服务器会报错并返回空 token，客户端调用会失败。

拿到 token 后，服务器创建 OAuth2 客户端并注入凭证，再实例化 Gmail 与 People 两个 API 客户端（见 mcp_servers/gmail/src/index.ts）：

const auth = new google.auth.OAuth2(); auth.setCredentials({ access_token: accessToken }); const gmailClient = google.gmail({ version: 'v1', auth }); const peopleClient = google.people({ version: 'v1', auth });

如果使用 Klavis 托管 OAuth，其认证流程在 _oauth_support/README.md 中有完整描述：容器启动时由entrypoint_wrapper.sh调用 _oauth_support/oauth_acquire.sh，脚本先调用 Klavis API 创建 OAuth 实例、向用户展示授权链接，再以最长 10 分钟的轮询等待用户完成授权，最终将获取到的认证数据写入AUTH_DATA环境变量，随后才启动真正的 MCP 服务器。相关环境变量包括：

变量	作用
KLAVIS_API_KEY	Klavis API 密钥，托管 OAuth 流程必需
AUTH_DATA	认证数据（JSON，含access_token），由脚本写入、服务器读取
SKIP_OAUTH	设为true可完全跳过 OAuth 认证流程（默认false），便于测试或使用预先配置的凭证

四、工具详解与参数说明

服务器共暴露 10 个工具，均通过 Zod Schema 做运行时校验并自动生成 JSON Schema（见 mcp_servers/gmail/src/index.ts）。每个工具还带有annotations分类标注（如GMAIL_EMAIL、GMAIL_BATCH_EMAIL、GMAIL_CONTACTS）和readOnlyHint只读标记，供客户端优化调用策略。

4.1 邮件发送：gmail_send_email / gmail_draft_email

两个工具共用同一份参数 Schema：

参数	类型	必填	默认值	说明
to	string[]	是	-	收件人列表，禁止臆测邮箱地址，可先用联系人搜索获取
subject	string	是	-	邮件主题
body	string	是	-	纯文本正文（未提供htmlBody时使用）
htmlBody	string	否	-	HTML 版本正文
mimeType	enum	否	text/plain	text/plain、text/html或multipart/alternative
cc/bcc	string[]	否	-	抄送 / 密送列表
threadId	string	否	-	回复时指定目标线程 ID
inReplyTo	string	否	-	被回复邮件的 Message ID

邮件内容的 MIME 组装逻辑在 mcp_servers/gmail/src/utl.ts 中实现，几个关键细节：

• 自动降级为 multipart/alternative：当同时提供htmlBody且mimeType未显式指定为text/plain时，自动生成同时包含纯文本与 HTML 的 multipart 邮件；
• RFC 2047 头编码：主题等头部若含非 ASCII 字符，会自动编码为=?UTF-8?B?...?=形式，保证中文等字符不乱码；
• 收件人校验：每个收件人地址都会经过正则校验，非法地址直接抛错；
• 线程关联：inReplyTo会自动写入In-Reply-To与References头，threadId会附加到 Gmail API 请求中，确保回复能归入原线程；
• 最终邮件以 Base64URL 编码后调用users.messages.send（发送）或users.drafts.create（存草稿）。

4.2 邮件读取与搜索：gmail_read_email / gmail_search_emails

• gmail_read_email：传入messageId，以format: 'full'拉取完整邮件，并自动获取所在线程的全部消息，返回结构化数组。每条消息包含messageId、subject、from、to、cc、date、正文（text/html/preferredFormat）以及附件元信息。正文提取采用递归遍历 MIME 结构的方式（mcp_servers/gmail/src/index.ts），可正确处理多层嵌套的 multipart 邮件。
• gmail_search_emails：传入 Gmail 搜索查询串（如from:[e-mail]）与maxResults（默认 10），先列出匹配消息，再以format: 'metadata'拉取每条消息的主题、发件人、日期摘要。

4.3 邮件管理：gmail_modify_email / gmail_delete_email

• gmail_modify_email：messageId+addLabelIds（添加标签，如实现"标记已读"）/removeLabelIds（移除标签，如实现"归档"），对应 Gmail 的users.messages.modify；
• gmail_delete_email：messageId，调用users.messages.delete永久删除邮件（不可恢复），请谨慎授权给 Agent。

4.4 批量操作：gmail_batch_modify_emails / gmail_batch_delete_emails

面向大规模清理场景设计，两个工具均支持：

参数	类型	默认值	说明
messageIds	string[]	-	待处理的 Message ID 列表
addLabelIds/removeLabelIds	string[]	-	批量添加/移除的标签（仅 modify 工具）
batchSize	number	50	每批并行处理的消息数

底层通过processBatches分批并行处理（mcp_servers/gmail/src/index.ts）：先按batchSize切块并行执行；若整个批次失败，会降级为逐条重试，避免单条失败导致整批中断。返回结果包含successCount、failureCount，失败时附带每条失败消息的 ID 与错误信息。

4.5 附件解析：gmail_get_email_attachments

按messageId递归收集邮件全部附件（支持嵌套 MIME part），逐一下载并按其类型处理：

附件类型	处理方式	底层库
PDF	逐页提取纯文本，标注页码	pdfjs-dist（Mozilla PDF.js）
Word.docx	提取原始文本	mammoth
Excel.xlsx	按工作表逐行输出为 CSV 风格文本	exceljs
文本类（text/*、JSON、XML 等）	直接以 UTF-8 解码输出	-
图片 / 音频	以 base64 二进制内容块返回	-
其他二进制	以 data URI 引用形式返回	-

实现见 mcp_servers/gmail/src/utl.ts 与 mcp_servers/gmail/src/index.ts。需要注意两个明确的限制：旧版.xls格式不支持文本提取（会提示转成.xlsx后重试），.doc同样不被mammoth支持；Gmail 返回的 base64url 数据会先经过填充补位转换（mcp_servers/gmail/src/index.ts）再交给解析库。

4.6 联系人搜索：gmail_search_contacts

这是本服务器最具特色的工具，基于 People API 支持多源联系人检索，参数如下：

参数	类型	默认值	说明
query	string	-	匹配姓名、邮箱、电话号码的搜索关键词
contactType	enum	all	all/personal/other/directory
pageSize	number	10	每页结果数（personal/other 上限 30，directory 上限 500）
pageToken	string	-	分页令牌（用于 directory 类型）
directorySources	enum	UNSPECIFIED	目录来源，见下表

四种检索类型：

• all（默认）：并行发起三类搜索（personal、other、directory），返回三个相互独立的结果集，每个结果集自带nextPageToken，可分别独立分页；
• personal：检索你已保存的联系人（people.searchContacts）；
• other：检索其他联系人来源（Gmail 建议联系人等，otherContacts.search）；
• directory：检索企业域名目录与域名联系人（需directory.readonly授权范围，searchDirectoryPeople）。

目录来源（directorySources）取值：

取值	含义
UNSPECIFIED	同时搜索DOMAIN_PROFILE（域名档案）与DOMAIN_CONTACT（域名联系人），默认
DOMAIN_DIRECTORY	仅搜索域名档案
DOMAIN_CONTACTS	仅搜索域名联系人

每个联系人结果包含resourceName、displayName、姓名拆分、邮箱地址（含类型）、电话号码（含类型）与组织信息（名称/职位）。

实现细节：每次检索前会先发送一次空查询的"预热请求"（warmupContactSearch，见 mcp_servers/gmail/src/index.ts）以更新 Google 侧缓存，提升后续实际搜索的性能；预热失败仅告警不影响主流程。分页上，personal/other 的pageSize会被钳制到最大 30，directory 钳制到最大 500，超出部分自动截断。

五、服务器运行原理：双传输协议

从 mcp_servers/gmail/src/index.ts 可以看出，服务器基于 Express 同时提供两套 MCP 传输：

• Streamable HTTP（主推，协议版本 2025-03-26）：POST /mcp端点处理所有 JSON-RPC 请求，每个请求内联初始化 Gmail/People 客户端；GET /mcp与DELETE /mcp返回 405。这也是 MCP 客户端配置中"url": "http://localhost:5000/mcp/"对应的端点；
• HTTP+SSE（已弃用，协议版本 2024-11-05）：GET /sse建立 SSE 连接，POST /messages接收客户端消息，按sessionId路由到对应 transport。

由于每个请求都可能携带不同的x-auth-data凭证，服务器使用AsyncLocalStorage（mcp_servers/gmail/src/index.ts）将请求级的 Gmail/People 客户端上下文传递到工具处理器中，从而支持多用户共用同一服务实例。端口由PORT环境变量控制，默认 5000。

六、本地构建与 MCP 客户端接入

从源码构建（以 Docker 镜像流程为参照）：

npm install --ignore-scripts # 安装依赖（忽略 prepare 脚本） npm run build # tsc 编译到 build/ npm start # node build/src/index.js 启动

要求 Node.js >= 20（见 mcp_servers/gmail/package.json）。构建产物同时提供bin入口gmail-mcp，可直接以 CLI 方式启动。

启动后，在任意 MCP 客户端中配置：

{ "mcpServers": { "gmail": { "url": "http://localhost:5000/mcp/" } } }

若使用 Klavis 托管服务，则按官方文档 docs/mcp-server/gmail.mdx 的方式创建 Strata MCP Server：调用create_strata_server（Python）或createStrataServer（TypeScript）并指定servers=[McpServerName.GMAIL]与userId，随后打开返回的 OAuth URL 完成授权即可拿到 MCP 端点 URL。

七、贡献与许可

• 贡献：欢迎提交 Issue 与 PR，贡献指南见 CONTRIBUTING.md；
• 许可：服务器源码采用 Apache 2.0 协议，详见 LICENSE（注意：package.json中声明的包级 license 为 MIT，实际以仓库根目录 LICENSE 为准）。

结语

Gmail MCP Server 将 Gmail 与 Google People 两大 API 的能力完整封装为 10 个标准 MCP 工具，覆盖从单封邮件到批量操作、从纯文本到 PDF/Word/Excel 附件解析、从个人联系人到企业域目录检索的完整场景。配合 Klavis 托管 OAuth 或AUTH_DATA手动凭证两种认证模式，无论是托管使用、Docker 自托管还是本地源码运行，都可以快速为 AI Agent 接上可靠的 Gmail 能力。更多服务器用法可进一步阅读 docs/mcp-server/overview.mdx 与 docs/concepts/mcp.mdx。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis