# @aaronsb/google-workspace-mcp 中文文档
规范地址：https://npmcn.com/package/%40aaronsb/google-workspace-mcp/
版本：4\.8\.0
npm 元数据更新时间：2026-10-16T16:54:46.981Z
中文译文更新时间：2026-11-06T02:59:31.222Z
软件包许可：Apache-2\.0
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40aaronsb/google-workspace-mcp
原文对照：https://npmcn.com/package/%40aaronsb/google-workspace-mcp/?lang=original
项目主页：https://github.com/aaronsb/google-workspace-mcp#readme
源码仓库：https://github.com/aaronsb/google-workspace-mcp
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：1.5 MB，267 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.12\.0
- 运行依赖：3 个
- 首次发布：2026-03-19T03:03:15.896Z
- 最新版本发布：2026-10-16T16:54:46.616Z
- 近 30 天下载量：6052（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）
## 中文简介
用于 Google 工作空间的 MCP 服务器, 并有渐进的背景披露和多账户协调
## 安装
```sh
npm install @aaronsb/google-workspace-mcp
```
也可以使用：`pnpm add @aaronsb/google-workspace-mcp`、`yarn add @aaronsb/google-workspace-mcp`、`bun add @aaronsb/google-workspace-mcp`
## README
# Google 工作空间 MCP 服务器
[](https://www.npmjs.com/package/@aaronsb/google-workspace-mcp) [](https://github.com/aaronsb/google-workspace-mcp/releases) [](https://nodejs.org/) [](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/LICENSE)
**让您的 AI 代理真实访问 Google 工作空间** ——Gmail, Calendar, Drive, Docs, Sheets, Tasks, Meet and Contacts——来自一个MCP服务器,横跨尽可能多的账户.
搜索您的邮件,检查您的日历,写一个医生,提交一个任务——在对话中,作为你自己.
## 安装
首先,你必须 **谷歌 OAuth 证书** - 每一条道路的共同先决条件:
1. 转到 [控制台.cloud.google.com/apis/证书](https://console.cloud.google.com/apis/credentials)
2. 创建一个 **OAuth 2.0 客户端标识**,应用程序类型 **桌面应用程序**
3. 启用您想要的 API( 邮件、 日历、 驱动器、 工作表、 文件、 任务、 满足—— 和) **人民协会** 对于联系人,Google在控制台上称之为联系人)
4. 留着 **客户身份** 财务报告和审定财务报表 **客户端机密** 方便,你会贴在下面
然后选择与工作方式相匹配的路径. 三个都运行同一服务器.
节点22.12或更新. (节点18和20均为报废. )
* * *
### \* \* \* \* \* \* \* \* 克洛德·桌面——一击 `.mcpb` 安装( 建议)
下载 **`google-workspace-mcp.mcpb`** 从 [最新发布](https://github.com/aaronsb/google-workspace-mcp/releases/latest),则 **拖到 Claude 桌面窗口**,或双击.
Claude 桌面打开安装对话框, 包含三个字段:
| 外地 | |
| --- | --- |
| **Google OAuth 客户端标识** | 所需 -- -- 从上文步骤 |
| **Google OAuth 客户端机密** | 所需 -- -- 从上文步骤 |
| **工作空间目录** | 可选的——其中附件,下载和输出为地. 默认为 `~/.local/share/google-workspace-mcp/workspace/`。给它一个专用文件夹——而不是您的家、文档、桌面或Google Drive文件夹. |
粘贴,击出"保存",完成. 没有JSON可以编辑,没有节点可以安装,没有路径可以得到正确的——捆绑携带服务器和每一个依赖.
**每个平台都有一个包** ——macOS(英特尔和苹果硅),Linux(x64和ARM64),和Windows. 没有什么可以选择的:服务器是纯JavaScript的,所以没有特定平台的有效载荷可以选择在两者之间.
> _跨平台注释 :_ `.mcpb` 文件通过克洛德桌面的捆绑处理器安装. 如果双击没有触发克洛德在您的系统中,则将文件拖到克洛德桌面窗口上,或者右击 → " Open with..." 并选择克洛德桌面(然后,如果您的OS主动提出"永远用"打开). 行为不一:macOS通常自动关联,Windows可能需要一次性关联,Linux因桌面环境而异.
* * *
### Claude 代码——一个命令
```bash
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`克劳德・科德, `.mcp.json`:
```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"
}
}
}
}
```
或者在全球安装,直接指向二进制:
```bash
npm install -g @aaronsb/google-workspace-mcp
```
## 如何融为一体
```mermaid
flowchart LR
human["🧑 You
ask in plain language"]
agent["🤖 Your AI agent
Claude Desktop, Claude Code…"]
server["⚙️ This MCP server
picks the right account,
builds the real request"]
keys[("🔑 Your accounts
OAuth tokens, kept
on your own machine")]
google["☁️ Google
Gmail · Calendar · Drive · Docs
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
+ 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个谷歌服务的12个工具**,加上多账户处理,每个账户只读访问,批量执行,内容编写,和一个文件沙盒.
| 工具 | 它会做什么 |
| --- | --- |
| `manage_email` | Gmail — 搜索, 读取( 平面或 sanited HTML), 发送, 回复/ 回复全部, 转发, 分类, 垃圾, 草稿( 列表/ 删除), 标签, 线程, 附件 |
| `manage_calendar` | 日历——列表,议程,获取,创建,快速Add(自然语言),更新,删除,日历,freebusy |
| `manage_drive` | 驱动器 — 搜索、 获取、 上传、 下载、 复制、 重命名/ 移动、 删除、 导出、 权限、 评论、 查看图像 |
| `manage_sheets` | 工作表 — 读取/ 写入范围( row- 数字输出) , 附加, 清除, 管理标签, 复制/ 复制/ 重命名 |
| `manage_docs` | Docs — 获取、创建、附加、插入文本、查找和替换 |
| `manage_tasks` | 任务——列表/创建/更新/完成任务和任务列表 |
| `manage_meet` | 开会——创造和配置会议空间,看现在是谁在打电话,浏览过去的会议、与会者、记录稿、录音、智能笔记 |
| `manage_contacts` | 联系人 – 在您保存的联系人中查找人, 您只对应的地址以及您的组织目录; 创建、 更新和删除联系人 |
| `manage_accounts` | 多账户周期——增加账户,管理证书和范围 |
| `manage_scratchpad` | 编译/编辑多行内容(线-或 JSON- path- addressed), 附加文件, 发送到任何目标; JSON 模式活同步到 Docs / 工作表 |
| `manage_workspace` | 工作空间沙盒中的文件操作( 附件、下载、导出交换点) |
| `bulk_operations` | 在一个呼叫中做许多事情——按顺序将不同的操作与 `$N.field` 引用,或在一个Google请求中对许多资源应用一个操作(`queue_operations` 仍然作为别名工作) |
每一个反应都带有 **下一步** 引导,所以代理总是知道 下一步可以做什么.
## 一个问,许多步骤
有用的部分不是任何单一的操作,而是你的经纪人可以 **把它们串在一起**。 。 。 .
你问一件事。 代理商认为,它需要四个API呼叫, 顺序,每个喂下一个:
```mermaid
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
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.
```
二事使此相能通达. 每一次回复都告诉特工 **接下来它能做什么**所以,这不是猜测 在下一步。 还有 `bulk_operations` 让它运行整个链 **一通电话**,将每个结果输入下一个结果——所以"找到发票,归档,提醒我"是一次来回旅行而不是四次.
当工作是 _同样的_ 使用Google的一次请求
```
bulk_operations { mode: 'batch', tool: 'manage_email', operation: 'trash',
items: ['msg1', 'msg2', 'msg3', … ] }
```
两百条信息在一次往返中被浪费,而不是200条. 这在目的上是狭义的——它只在Google为其发布一种方法的情况下才有效,即今天的联系人(创建,更新,删除,获取)和Gmail(垃圾,标签更改). 在其它任何地方询问,答案则指定可以操作的操作名称,并将您指向连续模式,该模式随处可见.
## 问少了什么
此服务器曝光 **95次业务**达到79个 **257方法** Google出版这8个API. 它是一个专有的子集: 特工必须 _选择_ 在这些方法中,它必须权衡的每一个方法都是可以错误选择的。 拥有257个操作的工具的能力不比拥有95个的更强——它更难正确使用.
但判决是没有你的.
**→ [浏览谷歌发布的每一种方法](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/docs/api-surface.md)**
每个方法都被列出——它做什么,我们是否揭露,以及 **请求** 链接打开预填出的问题。 描述是Google自己的,被引用的逐字记录,页面由客户端构建的相同规格生成,因此无法从现实中漂移.
该页还列出了 **3个完整的API 此服务器尚未触摸** 聊天、幻灯片和表格,原因相同: _非目标_ 是一个决定,而不是自然的事实.
不错的要求 **命名任务,而不是方法**数字 :
> _"我要经纪人自动将收到的发票存入文件夹"_
这一点可以评估。 它可能证明一个已有的操作已经这样做了,或者正确的答案是一个不同于你找到的方法. _"发表 `users.settings.filters.create`" (中文(简体) )_ 这是一种结论,而不是一种案例——首先解决问题,然后让方法遵循.
## 为什么是Apache 2.0,而不是打开核心
**一切都在这里.** 没有付费等级,没有"企业"的建设,没有特性可以留待日后出售. 你安装的是存在的东西.
开放核心通过保持好部分后退. 自由的东西是铅磁铁,一旦你的使用变得严肃,你就会发现你需要生命的操作在许可证后面. 这个模型会特别烂 _这里_这是一块管道 你和 **您自己的数据**,使用 **您自己的谷歌证书**运行中 **自己的机器**任何关于这种安排的东西都不应该有一个支付墙的中间,也不需要一个供应商.
[Apache 2.0 (英语)](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/LICENSE) 而不是麻省理工学院,原因有两个:
- **明确授予专利权.** 贡献者将他们的专利要求连同他们的密码一起许可,所以使用这个方法以后不能成为专利问题. 麻省理工学院对专利保持沉默,这意味着这个问题只是没有得到答复,而不是得到解决.
- **工作上收养是安全的.** Apache 2.0 基本上在每个公司的许可名单上。 把它叉出,卖出,装入商业产品里去——你什么都不欠任何人,你不需要问.
一项义务是归责:保持通知([`NOTICE`](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/NOTICE), (中文(简体) ), [`LICENSE`](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/LICENSE)与代码。 就是这样.
通过v3.0.0,这个项目得到了麻省理工学院的许可,历史被保存下来而不是被抹去——麻省理工学院时代的捐款保持了最初的通知 [`LICENSE-MIT`](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/LICENSE-MIT),并且他们的作者记入 [`NOTICE`](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/NOTICE)阿帕奇2.0拿回了麻省理工学院不允许的.
## 使用量
添加账户( 为 OAuth 打开浏览器) :
```
manage_accounts { "operation": "authenticate" }
```
然后使用您账户电子邮件的任何工具 :
```
manage_email { "operation": "triage", "email": "you@gmail.com" }
manage_calendar { "operation": "agenda", "email": "you@gmail.com" }
manage_drive { "operation": "search", "email": "you@gmail.com", "query": "quarterly report" }
```
### 提供账户只读访问
有些账户永远不应写入。 同意时要求少一点 **符号本身** 无法发送、编辑或删除 —— 这不是在宽符号上分层的规则 :
```
manage_accounts { "operation": "scopes", "email": "you@gmail.com",
"services": "gmail,drive,contacts", "access": "read" }
```
Google被要求每个范围只读的变体,所以在同意屏幕上勾选每个框仍然产生只读的符号. `manage_accounts status` 报告每个账户的实际持有情况.
在请求离开之前,只读账户的写作被拒绝,并附有账户、操作和回路:
```
'create' needs write access to contacts. Account you@gmail.com was authorized
read-only for contacts. Re-authorize with manage_accounts {operation:'scopes',
email:'you@gmail.com', services:'contacts', access:'readwrite'}, or use an
account that already has it.
```
如果一个服务没有只读范围, 你被告知哪些,他们还能做什么 **在此之前** 浏览器打开.
### 多步骤工作流程
带结果参考的链路操作——一个步骤的输出为下一个步骤提供了信息:
```json
{
"operations": [
{ "tool": "manage_email", "args": { "operation": "search", "email": "you@gmail.com", "query": "from:boss subject:review" }},
{ "tool": "manage_email", "args": { "operation": "read", "email": "you@gmail.com", "messageId": "$0.messageId" }}
]
}
```
### 一个行动,很多事情
Google发布方法时
```json
{
"mode": "batch",
"tool": "manage_contacts",
"operation": "delete",
"email": "you@gmail.com",
"items": ["people/c1", "people/c2", "people/c3"]
}
```
整个批量共享的任何东西都是在顶层; `items` 只携带不同的东西——光是身份就足够了.
## 你的数据所在的地方
遵循 XDG 基础目录规格 :
| 数据 | 地点 |
| --- | --- |
| 账户登记册 | `~/.config/google-workspace-mcp/accounts.json` |
| 全权证书 | `~/.local/share/google-workspace-mcp/credentials/` |
| 工作空间( 文件交换) | `~/.local/share/google-workspace-mcp/workspace/` |
证书是每个账户的文件,持有标准的OAuth令牌. 项目目录中不存储任何秘密 .
## 在车盖下
你不需要这些东西来使用服务器. 但是,如果你好奇, 或者你想增加一个操作:
服务器构建其 Google API 客户端 **从谷歌自己的机器可读API规格**. 无一是用手来转写,所以表面无法从现实中漂移出,而添加一个操作是YAML编辑而不是代码更改.
- **[如何运作](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/docs/how-it-works.md)** ——建设时间/运行时间分拆,描述器,工厂
- **[API 覆盖率](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/docs/coverage.md)** ——什么暴露了,什么没有,如何要求更多
- **[完整的 API 表面](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/docs/api-surface.md)** ——谷歌发布的每一种方法,加上我们尚未针对的三个API
- **[结构决定](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/docs/architecture/)** —— ADRs,包括为什么这个服务器直接拥有其Google客户端
## 许可证
[Apache 许可证 2.0](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/LICENSE) 看到了吗 [为什么是Apache 2.0](https://npmcn.com/package/%40aaronsb/google-workspace-mcp/#readme-why-apache-20-and-not-open-core) 见上文.
## 常见问题
### @aaronsb/google-workspace-mcp 是什么？
用于 Google 工作空间的 MCP 服务器, 并有渐进的背景披露和多账户协调
### 如何安装 @aaronsb/google-workspace-mcp？
在项目目录运行 npm install @aaronsb/google-workspace-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 google-workspace-mcp，可以用 npx google-workspace-mcp 直接运行。
### @aaronsb/google-workspace-mcp 支持 TypeScript 吗？
该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aaronsb\_\_google-workspace-mcp 是否存在。
### @aaronsb/google-workspace-mcp 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @aaronsb/google-workspace-mcp 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @aaronsb/google-workspace-mcp 可以商用吗？
@aaronsb/google-workspace-mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。
### @aaronsb/google-workspace-mcp 的下载量有多少？
根据 npm 官方下载统计，@aaronsb/google-workspace-mcp 在 2026/10/05 – 2026/11/03 这 30 天内被下载 6,052 次，日均约 202 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @aaronsb/google-workspace-mcp 还在维护吗？
最新版本 4\.8\.0 发布于 2026/10/17（22 天前）；至今共发布 29 个版本，其中过去 12 个月发布了 29 个；首次发布于 2026/03/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。