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 Servermcp_servers/gmail的完整技术指南。它以 Model Context ProtocolMCP协议封装 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 klavisfrom klavis import Klavis klavis Klavis(api_keyyour-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环境变量AUTH_DATAJSON 字符串需包含access_token字段如{access_token:ya29.xxx}请求头x-auth-data对同样的 JSON 做 Base64 编码后放入该请求头服务器会解码并解析出access_token适合多租户场景下按请求注入不同凭证两者都未提供时服务器会报错并返回空 token客户端调用会失败。拿到 token 后服务器创建 OAuth2 客户端并注入凭证再实例化 Gmail 与 People 两个 API 客户端见 mcp_servers/gmail/src/index.tsconst 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_KEYKlavis 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参数类型必填默认值说明tostring[]是-收件人列表禁止臆测邮箱地址可先用联系人搜索获取subjectstring是-邮件主题bodystring是-纯文本正文未提供htmlBody时使用htmlBodystring否-HTML 版本正文mimeTypeenum否text/plaintext/plain、text/html或multipart/alternativecc/bccstring[]否-抄送 / 密送列表threadIdstring否-回复时指定目标线程 IDinReplyTostring否-被回复邮件的 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_emailsgmail_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:examplegmail.com与maxResults默认 10先列出匹配消息再以format: metadata拉取每条消息的主题、发件人、日期摘要。4.3 邮件管理gmail_modify_email / gmail_delete_emailgmail_modify_emailmessageIdaddLabelIds添加标签如实现标记已读/removeLabelIds移除标签如实现归档对应 Gmail 的users.messages.modifygmail_delete_emailmessageId调用users.messages.delete永久删除邮件不可恢复请谨慎授权给 Agent。4.4 批量操作gmail_batch_modify_emails / gmail_batch_delete_emails面向大规模清理场景设计两个工具均支持参数类型默认值说明messageIdsstring[]-待处理的 Message ID 列表addLabelIds/removeLabelIdsstring[]-批量添加/移除的标签仅 modify 工具batchSizenumber50每批并行处理的消息数底层通过processBatches分批并行处理mcp_servers/gmail/src/index.ts先按batchSize切块并行执行若整个批次失败会降级为逐条重试避免单条失败导致整批中断。返回结果包含successCount、failureCount失败时附带每条失败消息的 ID 与错误信息。4.5 附件解析gmail_get_email_attachments按messageId递归收集邮件全部附件支持嵌套 MIME part逐一下载并按其类型处理附件类型处理方式底层库PDF逐页提取纯文本标注页码pdfjs-distMozilla PDF.jsWord.docx提取原始文本mammothExcel.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 支持多源联系人检索参数如下参数类型默认值说明querystring-匹配姓名、邮箱、电话号码的搜索关键词contactTypeenumallall/personal/other/directorypageSizenumber10每页结果数personal/other 上限 30directory 上限 500pageTokenstring-分页令牌用于 directory 类型directorySourcesenumUNSPECIFIED目录来源见下表四种检索类型all默认并行发起三类搜索personal、other、directory返回三个相互独立的结果集每个结果集自带nextPageToken可分别独立分页personal检索你已保存的联系人people.searchContactsother检索其他联系人来源Gmail 建议联系人等otherContacts.searchdirectory检索企业域名目录与域名联系人需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会被钳制到最大 30directory 钳制到最大 500超出部分自动截断。五、服务器运行原理双传输协议从 mcp_servers/gmail/src/index.ts 可以看出服务器基于 Express 同时提供两套 MCP 传输Streamable HTTP主推协议版本 2025-03-26POST /mcp端点处理所有 JSON-RPC 请求每个请求内联初始化 Gmail/People 客户端GET /mcp与DELETE /mcp返回 405。这也是 MCP 客户端配置中url: http://localhost:5000/mcp/对应的端点HTTPSSE已弃用协议版本 2024-11-05GET /sse建立 SSE 连接POST /messages接收客户端消息按sessionId路由到对应 transport。由于每个请求都可能携带不同的x-auth-data凭证服务器使用AsyncLocalStoragemcp_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_serverPython或createStrataServerTypeScript并指定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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考