google-mcp

用途

google-mcp 是一个面向 MCP（Model Context Protocol）协议的 Google 原生工具集合，旨在与 Claude、Cursor 等 AI 客户端无缝集成。它把 Gmail、Google Calendar、Google Drive、Google Tasks 等 Google 服务封装成 AI 可调用的工具，让用户可以用自然语言驱动这些服务完成日常操作。项目支持通过 .mcpb 一键安装，也提供手动安装方式。

主要能力

Gmail

发送邮件，支持多个收件人（to、cc、bcc），并可从本地文件或 Google Drive 添加附件。
将邮件附件下载到本地存储，支持跨平台。
按自定义查询、标签和结果数量列出邮件。
按 ID 读取指定邮件，并显示附件信息。
管理标签（添加、移除、列出）。
创建草稿和删除邮件。

Calendar

列出日历并设置默认日历。
创建事件，可设置摘要、开始/结束时间、参与者等详情。
按可自定义的筛选条件列出即将到来的事件。
更新或删除已有事件。
查找可用于排期的空闲时间段。

Drive

使用搜索查询进行筛选。
按修改日期或其他条件排序。
自定义显示数量。
查看详细文件元数据。
读取文件内容（文本、文档、电子表格）。
创建指定内容的新文件。
更新已有文件。
删除文件（移入回收站或永久删除）。
以指定权限共享文件。

Tasks

查看所有任务列表。
创建新任务列表。
删除已有任务列表。
设置默认任务列表。
按筛选条件列出任务。
查看任务详情。
创建带标题、备注和截止日期的任务。
更新任务属性。
将任务标记为完成。
删除任务。

其他

Google Contacts：搜索和管理联系人。
更多功能仍在规划中（TODO Plans）。

v1.1.0 新增特性

邮件附件支持

从本地文件或 Google Drive 发送带附件的邮件。
将所有邮件附件下载到本地存储。
双附件来源：本地文件路径或 Google Drive 文件 ID。
智能文件处理：自动检测 MIME 类型并清理文件名。

增强的邮件能力

多来源附件：同一封邮件可同时附加本地存储和 Google Drive 中的文件。
自定义文件名：可覆盖附件的原始文件名。
文件大小校验：自动执行 Gmail 的 25MB 限制。
跨平台下载：自动检测 Windows、macOS 和 Linux 的 Downloads 文件夹。
冲突解决：自动重命名文件以防止覆盖。

新增与增强的工具

google_gmail_send_email：现支持来自本地文件和 Google Drive 的附件。
google_gmail_draft_email：创建带附件的草稿。
google_gmail_download_attachments：下载所有邮件附件，路径可自定义。

OAuth 管理

自动刷新过期的访问令牌。
无需重新认证即可更新令牌文件中的令牌。
通过自动令牌清理完成重新认证。
在长时间运行的操作中保持会话连续性。

使用方式

一键安装

项目提供 .mcpb 一键安装方式。

手动安装

前置条件：安装 Bun：

brew install oven-sh/bun/bun # macOS/Linux with Homebrew

设置 OAuth：

在 Google Cloud Console 中创建 Google Cloud 项目。
设置 OAuth 2.0 凭据（Client ID、Client Secret）。
类型选择 Desktop app。
如果使用测试模式，将你的邮箱加入测试用户列表。
确保为所需服务（Gmail、Calendar、Drive 等）启用 API 访问。

配置客户端：编辑 claude_desktop_config.json（或客户端对应的配置文件）。

认证：首次运行服务器时，会打开浏览器进行 OAuth 认证。按提示授予访问权限，令牌将保存到 GOOGLE_OAUTH_TOKEN_PATH。

之后即可让 Claude 使用 google-mcp 工具。

命令链式调用

可以串联命令形成工作流，例如： "List my unread emails, draft a reply to the latest one, and schedule a follow-up meeting tomorrow at 2 PM."

托管部署

Fronteir AI 上提供托管部署。

OAuth 令牌管理

服务器内置 OAuth 令牌管理，可优雅处理过期的访问令牌：

自动令牌刷新：访问令牌过期时，无需重新走完整 OAuth 流程即可刷新。
完整重新认证：自动处理刷新令牌无效或过期的情况。
持久化存储：刷新后的令牌自动保存到配置的令牌文件路径。
会话连续性：刷新后所有 Google 服务会用新令牌重新初始化。

刷新令牌：如果遇到认证错误或想主动刷新令牌，只需提出：

使用存储的刷新令牌获取新的访问令牌
用新凭据更新令牌文件
用新认证重新初始化所有 Google 服务
显示新的令牌过期时间

完整重新认证：如果遇到 invalid_grant 错误或刷新令牌已过期，可以重新开始。该自动化流程会：

从令牌文件中删除现有令牌
启动 OAuth 服务器处理回调
打开浏览器进行全新认证
自动保存新令牌
用新凭据重新初始化服务

你只需在浏览器中点击 "Allow"，其余全部自动化。注意：如果没有有效的刷新令牌，需要重新走初始 OAuth 认证流程。

传输支持

该 MCP 服务器通过环境变量同时支持 stdio 和 HTTP 传输：

Stdio 传输（默认）
HTTP 传输（Streamable HTTP）

HTTP 模式下的端点：

GET /health - 健康检查端点，含会话数
GET /mcp - 会话信息与服务器状态
POST /mcp - 主 MCP JSON-RPC 端点，用于发送请求
DELETE /mcp - 结束会话端点

会话管理：Streamable HTTP 传输使用官方 MCP SDK，具备自动会话管理：

自动会话：服务器自动生成安全会话 ID
SSE 流式传输：支持 Server-Sent Events 实时通信
JSON 响应：SSE 不可用时回退为 JSON 响应
DNS 保护：面向生产部署的内置安全特性

HTTP 传输配置：为 HTTP 传输配置客户端时，使用服务器 URL。

适用场景

在 AI 客户端中用自然语言管理 Gmail 邮件、附件、标签和草稿。
通过 AI 助手安排日历事件、查找空闲时间。
浏览、读取、创建、更新和共享 Google Drive 文件。
管理 Google Tasks 任务列表和任务。
将多个 Google 服务操作串联成自动化工作流。

限制

需要自行创建 Google Cloud 项目并配置 OAuth 2.0 凭据。
使用测试模式时需将邮箱加入测试用户列表。
需为所需服务启用 API 访问。
Gmail 附件有 25MB 大小限制。
手动安装需要先安装 Bun。
部分功能（如 Google Contacts 之外的更多工具）仍处于 TODO 规划阶段。