Google Workspace MCP Server

Google Workspace MCP 服务

让你的 AI Agent 真正访问 Google Workspace——通过一个 MCP 服务使用 Gmail、Calendar、Drive、Docs、Sheets、Tasks、Meet 和 Contacts，支持你拥有的任意数量的账号。

搜索邮件、查看日历、编写文档、创建任务——在对话中以你的身份操作。

安装

首先，你需要 Google OAuth 凭据——这是所有安装方式的共同前提：

1. 前往 console.cloud.google.com/apis/credentials
2. 创建 OAuth 2.0 Client ID，应用类型选择 Desktop app
3. 启用你需要的 API（Gmail、Calendar、Drive、Sheets、Docs、Tasks、Meet；联系人则需启用 People API，这是 Google 在控制台中的名称）
4. 准备好 Client ID 和 Client Secret，稍后需要粘贴

然后选择适合你的使用方式。三种方式运行的都是同一个服务。

需要 Node 22.12 或更高版本。（Node 18 和 20 均已停止维护。）

---

📦 → 🤖 Claude Desktop — 一键安装 .mcpb（推荐）

从最新版本下载 google-workspace-mcp.mcpb，然后将其拖到 Claude Desktop 窗口中，或双击文件。

Claude Desktop 会打开一个安装对话框，其中有三个字段：

字段
Google OAuth Client ID	必填——来自上述步骤
Google OAuth Client Secret	必填——来自上述步骤
Workspace Directory	可选——附件、下载文件和导出文件的保存位置。默认为 ~/.local/share/google-workspace-mcp/workspace/。请指定一个专用文件夹，不要使用你的主目录、Documents、Desktop 或 Google Drive 文件夹。

粘贴信息，点击 Save，完成。无需编辑 JSON、安装 Node 或设置路径——这个安装包包含服务及其所有依赖项。

一个安装包适用于所有平台——macOS（Intel 和 Apple Silicon）、Linux（x64 和 ARM64）以及 Windows。无需选择：该服务完全由 JavaScript 编写，因此没有需要按平台挑选的特定载荷。

跨平台说明： .mcpb 文件通过 Claude Desktop 内置的处理程序安装。如果在你的系统上双击文件无法启动 Claude，请将文件拖到 Claude Desktop 窗口中，或右键点击 → “打开方式…”并选择 Claude Desktop（如果操作系统提供“始终使用此应用打开”，也可选择该选项）。具体行为因系统而异：macOS 通常会自动关联，Windows 可能需要进行一次关联设置，Linux 则因桌面环境而异。

---

Claude Code — 一条命令

claude mcp add google-workspace \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- npx -y @aaronsb/google-workspace-mcp

就这么简单——无需编辑文件。使用 /mcp 验证。

---

其他 MCP 客户端

在客户端的 MCP 配置文件中添加一项（手动配置 Claude Desktop 时使用 claude_desktop_config.json；Claude Code 使用 .mcp.json）：

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "@aaronsb/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

或者全局安装，并直接指向二进制文件：

npm install -g @aaronsb/google-workspace-mcp

工作原理

flowchart LR
    human["🧑 You<br>ask in plain language"]
    agent["🤖 Your AI agent<br>Claude Desktop, Claude Code…"]
    server["⚙️ This MCP server<br>picks the right account,<br>builds the real request"]
    keys[("🔑 Your accounts<br>OAuth tokens, kept<br>on your own machine")]
    google["☁️ Google<br>Gmail · Calendar · Drive · Docs<br>Sheets · Tasks · Meet · Contacts"]

    human -->|"“what's on my calendar?”"| agent
    agent -->|"tool call"| server
    server <-->|"which account?"| keys
    server -->|"real API call, as you"| google
    google -->|"your data"| server
    server -->|"shaped for an agent<br>+ what to do next"| agent
    agent -->|"an answer"| human

    classDef person   fill:#475569,color:#ffffff,stroke:#94a3b8
    classDef robot    fill:#2d7d9a,color:#ffffff,stroke:#4a5568
    classDef ours     fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
    classDef secrets  fill:#2d8e5e,color:#ffffff,stroke:#4a5568
    classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706

    class human person
    class agent robot
    class server ours
    class keys secrets
    class google external

你的凭据绝不会离开你的设备。 服务会在你自己的磁盘上为每个账号保存一个 OAuth 令牌，并以你的身份调用 Google——没有中间服务，没有我们的账号，也无需注册。你可以添加任意数量的账号（个人和工作账号可以并用）；服务会将每个请求路由到相应的账号。

功能

涵盖 8 项 Google 服务的 12 个工具，还支持多账号处理、按账号设置只读访问、批量执行、内容创作和文件沙箱。

工具	功能
manage_email	Gmail — 搜索、读取（纯文本或经过净化的 HTML）、发送、回复 / 回复全部、转发、分类处理、移至垃圾箱、草稿（列出 / 删除）、标签、会话、附件
manage_calendar	Calendar — 列出、日程、获取、创建、quickAdd（自然语言）、更新、删除、日历、空闲 / 忙碌状态
manage_drive	Drive — 搜索、获取、上传、下载、复制、重命名 / 移动、删除、导出、权限、评论、查看图片
manage_sheets	Sheets — 读取 / 写入范围（输出带行号）、追加、清除、管理工作表标签、复制 / 复制副本 / 重命名
manage_docs	Docs — 获取、创建、追加、插入文本、查找并替换
manage_tasks	Tasks — 列出 / 创建 / 更新 / 完成任务和任务列表
manage_meet	Meet — 创建和配置会议空间、查看当前通话中的人员、浏览过往会议、参与者、转录文本、录制内容、智能笔记
manage_contacts	Contacts — 在已保存的联系人、仅有过邮件往来的地址，以及组织目录中查找人员；创建、更新和删除联系人
manage_accounts	多账号生命周期管理 — 添加账号、管理凭据和作用域
manage_scratchpad	编写 / 编辑多行内容（按行或 JSON 路径定位）、附加文件、发送到任意目标；JSON 模式会实时同步到 Docs / Sheets
manage_workspace	在工作区沙箱中执行文件操作（附件、下载和导出的交换点）
bulk_operations	一次调用执行多项操作 — 按顺序串联不同操作，并通过 $N.field 引用传递结果，或在一个 Google 请求中对多个资源执行同一操作（queue_operations 仍可用作别名）

每条响应都会提供后续步骤指引，让 Agent 始终知道接下来可以做什么。

一次请求，多个步骤

真正实用的并非某一项单独操作，而是 Agent 能够将它们串联起来。

你提出一项需求。Agent 会判断需要依次进行四次 API 调用，并将每一步的结果传给下一步：

sequenceDiagram
    autonumber
    participant H as 🧑 You
    participant A as 🤖 Your agent
    participant S as ⚙️ MCP server
    participant G as ☁️ Google

    H->>A: "file the invoice from Acme<br>and remind me to pay it Friday"
    A->>S: find the email
    S->>G: search Gmail
    G-->>S: the message
    S-->>A: found it — and here's what you can do next
    A->>S: save the attachment
    S->>G: download it
    A->>S: put it in Drive
    S->>G: upload
    A->>S: create a task, due Friday
    S->>G: Google Tasks
    A-->>H: Done. Invoice filed, task set for Friday.

有两点让这一切成为可能。每条响应都会告诉 Agent 接下来可以做什么，因此它不必猜测下一步。而 bulk_operations 可以让它在一次调用中运行完整链条，并将每一步的结果传给下一步——所以“找到发票、归档、提醒我”只需一次往返，而不是四次。

如果要对多个对象执行相同的操作，它还能更进一步，在一个 Google 请求中完成所有操作：

bulk_operations { mode: 'batch', tool: 'manage_email', operation: 'trash',
                  items: ['msg1', 'msg2', 'msg3', … ] }

一次往返即可将 200 封邮件移至垃圾箱，而不是往返 200 次。这种能力有意限定了适用范围——仅适用于 Google 提供相应方法的场景，目前包括 Contacts（创建、更新、删除、获取）和 Gmail（移至垃圾箱、更改标签）。如果你在其他场景请求此功能，回复会列出支持批量执行的操作，并引导你使用可在所有场景中使用的顺序执行模式。

提出缺少的功能

此服务提供 95 项操作，覆盖 Google 在这 8 个 API 中发布的 257 个方法里的 79 个。这是经过筛选的子集，而且是有意为之：Agent 必须在这些操作中做出选择，而它必须权衡的每个方法，都可能被它选错。拥有 257 项操作的工具并不比只有 95 项操作的工具更强大——只是更难正确使用。

但这个判断是在没有你参与的情况下做出的。

→ 浏览 Google 发布的所有方法

此页面列出了每个方法——它的用途、我们是否提供该方法，以及一个可打开预填问题的 Request 链接。描述直接引用 Google 的原文，且页面由构建客户端所用的同一份规范生成，因此不会与实际情况脱节。

此页面还列出了 此服务尚未接入的 3 个完整 API——Chat、Slides 和 Forms，原因也相同：尚未纳入目标范围是一个决定，而不是既定事实。

好的请求会描述任务，而不是方法：

“我希望 Agent 自动将收到的发票归档到文件夹中。”

这样的请求可以评估。最后可能发现现有操作已经能完成，也可能发现正确答案是另一个方法，而不是你找到的那个。*“公开 users.settings.filters.create”*只是结论，不是具体需求——先说明问题，再确定方法。

为什么选择 Apache 2.0，而不是开放核心模式

**所有内容都在这里。**没有付费层，没有“企业版”构建，也没有留着以后再出售的功能。你安装的，就是全部功能。

开放核心模式靠扣留优质功能运作。免费版是吸引用户的诱饵，一旦你的使用需求变得重要，你就会发现需要的操作被锁在许可证之后。这种模式在这里尤其糟糕：这是连接你与你自己的数据的基础设施，使用你自己的 Google 凭据，运行在你自己的机器上。这种安排不应该有付费墙横在中间，也不需要供应商。

选择 Apache 2.0 而非 MIT，有两个具体原因：

• **明确授予专利权。**贡献者会连同代码一起许可其专利权利要求，因此以后使用本项目不会引发专利问题。MIT 对专利问题只字未提，也就是说，这个问题只是悬而未决，而非已有定论。
• **适合在工作中采用。**Apache 2.0 几乎都在企业允许使用的许可证清单上。你可以 fork、作为依赖引入，也可以将其打包进商业产品——无需向任何人支付费用，也无需征求许可。

唯一的义务是注明出处：将声明文件（NOTICE、LICENSE）与代码一并保留。仅此而已。

在 v3.0.0 之前，本项目采用 MIT 许可；这段历史得到了保留，而非抹去——MIT 许可期间的贡献仍在 LICENSE-MIT 中保留原有声明，其作者也列于 NOTICE 中。Apache 2.0 不会收回 MIT 许可原本允许的任何权利。

用法

添加账号（将打开浏览器进行 OAuth）：

manage_accounts { "operation": "authenticate" }

然后使用账号邮箱调用任意工具：

manage_email    { "operation": "triage", "email": "[email protected]" }
manage_calendar { "operation": "agenda", "email": "[email protected]" }
manage_drive    { "operation": "search", "email": "[email protected]", "query": "quarterly report" }

为账号授予只读权限

有些账号绝不能执行写入操作。在同意授权时请求较少的权限，令牌本身就无法发送、编辑或删除内容——这不是在权限宽泛的令牌上再叠加一条规则：

manage_accounts { "operation": "scopes", "email": "[email protected]",
                  "services": "gmail,drive,contacts", "access": "read" }

系统会向 Google 请求每个范围对应的只读版本，因此即使在同意授权页面上勾选所有选项，最终得到的仍是只读令牌。manage_accounts status 会报告每个账号实际持有的权限。

只读账号发起的写入请求会在离开本地前被拒绝，并说明账号、操作以及如何恢复：

'create' needs write access to contacts. Account [email protected] was authorized
read-only for contacts. Re-authorize with manage_accounts {operation:'scopes',
email:'[email protected]', services:'contacts', access:'readwrite'}, or use an
account that already has it.

如果某项服务没有只读范围，系统会在浏览器打开前告知你是哪些范围，以及它们仍能执行哪些操作。

多步工作流

使用结果引用串联操作——某一步的输出会传给下一步：

{
  "operations": [
    { "tool": "manage_email", "args": { "operation": "search", "email": "[email protected]", "query": "from:boss subject:review" }},
    { "tool": "manage_email", "args": { "operation": "read", "email": "[email protected]", "messageId": "$0.messageId" }}
  ]
}

一次操作，处理多项内容

对于 Google 发布了相应方法的操作，处理多个资源只需一个请求：

{
  "mode": "batch",
  "tool": "manage_contacts",
  "operation": "delete",
  "email": "[email protected]",
  "items": ["people/c1", "people/c2", "people/c3"]
}

整个批次共享的内容放在顶层；items 只包含各项不同的内容——如果只需一个 ID，直接提供即可。

数据存储位置

遵循 XDG 基目录规范：

数据	位置
账户注册表	~/.config/google-workspace-mcp/accounts.json
凭据	~/.local/share/google-workspace-mcp/credentials/
工作区（文件交换）	~/.local/share/google-workspace-mcp/workspace/

凭据是按账户分别存储的文件，其中包含标准 OAuth 令牌。项目目录中不会存储任何机密信息。

内部原理

使用此服务无需了解以下内容。不过，如果你好奇，或者想添加一项操作：

此服务根据 Google 自己的机器可读 API 规范构建 Google API 客户端。所有内容都不是手动转录的，因此接口不会偏离实际情况；添加操作只需编辑 YAML，而无需更改代码。

• 工作原理 — 构建时与运行时的划分、描述符和工厂
• API 覆盖范围 — 已开放和未开放的内容，以及如何申请添加
• 完整 API 接口 — Google 发布的所有方法，以及目前尚未支持的三个 API
• 架构决策 — 架构决策记录（ADR），包括此服务为何完全自行管理 Google 客户端

许可证

Apache License 2.0 — 另请参阅上文的为何选择 Apache 2.0 而非开放核心模式。