# @dguido/google-workspace-mcp 中文文档

规范地址：https://npmcn.com/package/%40dguido/google-workspace-mcp/

版本：3\.4\.4
npm 元数据更新时间：2026-02-22T23:42:02.374Z
中文译文更新时间：2026-11-12T06:50:53.873Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dguido/google-workspace-mcp
原文对照：https://npmcn.com/package/%40dguido/google-workspace-mcp/?lang=original
项目主页：https://github.com/dguido/google-workspace-mcp
源码仓库：https://github.com/dguido/google-workspace-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：8 个
- 首次发布：2026-01-22T22:28:52.160Z
- 最新版本发布：2026-02-22T23:42:02.064Z
- 近 30 天下载量：2743（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

Google 工作空间 MCP 服务器 - 模式上下文协议服务器,通过 MCP 客户端,例如 Claude 桌面,提供安全访问 Google Drive, Docs, Sheets, Slies, Calendar 和 Gmail 的功能

## 安装

```sh
npm install @dguido/google-workspace-mcp
```

也可以使用：`pnpm add @dguido/google-workspace-mcp`、`yarn add @dguido/google-workspace-mcp`、`bun add @dguido/google-workspace-mcp`

## README

# Google 工作空间 MCP 服务器

MCP服务器提供克洛德访问Google Drive,Docs, Sheds,幻灯片,日历,Gmail,以及联系方式.

## 快速启动

### 1\. 设置谷歌云

1.  转到 [谷歌云控台](https://console.cloud.google.com/) 创建或选择一个工程
2.  [启用所有需要的 API](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com,docs.googleapis.com,sheets.googleapis.com,slides.googleapis.com,calendar-json.googleapis.com,gmail.googleapis.com,people.googleapis.com) (一击链接)
3.  转到 [APIs 服务 > 全权证书](https://console.cloud.google.com/apis/credentials) 并创建 OAuth 2.0 客户端 ID( Desktop app 类型)
4.  复制 **客户身份** 财务报告和审定财务报表 **客户端机密**

### 2\. 配置克洛德桌面

**马科斯**数字 : `~/Library/Application Support/Claude/claude_desktop_config.json` **窗口**数字 : `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_WORKSPACE_SERVICES": "drive,gmail,calendar"
      }
    }
  }
}
```

就是这样。 在第一个工具呼叫中,一个浏览器窗口打开,以获得Google OAuth的同意. 自动保存指针 .

备选:基于文件的证书

从 Google Cloud Console 下载证书并保存到 `~/.config/google-workspace-mcp/credentials.json`,然后手动认证:

```bash
npx @dguido/google-workspace-mcp auth
```

见 [高级配置](https://npmcn.com/package/%40dguido/google-workspace-mcp/docs/ADVANCED.md) 用于基于文件的设置、命名配置文件以及多账户设置.

## 你能做什么吗

```
Create a Google Doc called "Project Plan" in /Work/Projects with an outline for Q1.
```

```
Search for files containing "budget" and organize them into the Finance folder.
```

```
Create a presentation called "Product Roadmap" with slides for Q1 milestones.
```

## 谷歌云设置

### 1\. 创建谷歌云项目

-   转到 [谷歌云控台](https://console.cloud.google.com/)
-   点击“ 选择工程” > “ 新工程”
-   命名您的项目( 例如“ Google Drive MCP ”)

### 2\. 启用必要的API

-   [立即启用所有 API](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com,docs.googleapis.com,sheets.googleapis.com,slides.googleapis.com,calendar-json.googleapis.com,gmail.googleapis.com,people.googleapis.com) (一击链接)
-   或手动:去"APIS & Services" >"图书馆"并启用: **谷歌驱动 API**, (中文(简体) ), **谷歌文档 API**, (中文(简体) ), **谷歌工作表 API**, (中文(简体) ), **谷歌幻灯片 API**, (中文(简体) ), **谷歌日历 API**, (中文(简体) ), **Gmail API 邮件**, (中文(简体) ), **人民协会**

### 3\. 配置 OAuth 同意屏幕

-   转到“ AP Is & Services” > “ Outh 同意屏幕 ”
-   填写应用程序名称、 支持电子邮件和开发者联系人
-   选择“ 外部” (或“ 内部” 用于工作空间)
-   将您的电子邮件添加为测试用户
-   添加范围 : `drive.file`, (中文(简体) ), `documents`, (中文(简体) ), `spreadsheets`, (中文(简体) ), `presentations`, (中文(简体) ), `drive`, (中文(简体) ), `drive.readonly`, (中文(简体) ), `calendar`, (中文(简体) ), `gmail.modify`, (中文(简体) ), `gmail.labels`, (中文(简体) ), `contacts`

### 4\. 创建 OAuth 2.0 全权证书

-   转到"AP Is & Services" > "证书"
-   点击"+CREATE CREENTIALS" > "Outh客户端ID"
-   应用程序类型 : **桌面应用程序**
-   复制 **客户身份** 财务报告和审定财务报表 **客户端机密** (或下载 JSON 文件)

## 配置

### 文件位置

证书和证物都存放在 `~/.config/google-workspace-mcp/` 默认:

| 文件 | 默认路径 |
| --- | --- |
| 证书 | `~/.config/google-workspace-mcp/credentials.json` |
| 证书 | `~/.config/google-workspace-mcp/tokens.json` |

### 环境变量

| 变量 | 说明 |
| --- | --- |
| `GOOGLE_CLIENT_ID` | OAuth 客户端 ID( 最简单的设置——不需要证书文件) |
| `GOOGLE_CLIENT_SECRET` | OAuth 客户端机密( 用于 `GOOGLE_CLIENT_ID`(中文(简体) ) |
| `GOOGLE_WORKSPACE_MCP_TOKEN_PATH` | 自定义令牌存储位置 |
| `GOOGLE_WORKSPACE_MCP_PROFILE` | 证书隔离的命名配置文件 |
| `GOOGLE_WORKSPACE_SERVICES` | 以逗号分隔的服务列表 |

### Token- 有效产出( TON)

对于LLM-优化的将符号用量减少20%-50%的响应,启用TON格式:

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_WORKSPACE_SERVICES": "drive,gmail,calendar",
        "GOOGLE_WORKSPACE_TOON_FORMAT": "true"
      }
    }
  }
}
```

TON (Token-Oriented Object Notation) 通过去除重复的字段名称,将结构化的响应比JSON更紧凑. 列表操作(日历、事件、电子邮件、过滤器)节省得最多.

### 服务配置

默认情况下,我们建议只允许核心服务`drive,gmail,calendar`),如"快起"所显示. 这提供了文件管理,电子邮件和日历能力,而无需复杂的文件编辑工具.

为增加服务,请添加到 `GOOGLE_WORKSPACE_SERVICES`数字 :

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_WORKSPACE_SERVICES": "drive,gmail,calendar,docs,sheets,slides"
      }
    }
  }
}
```

**现有服务:** `drive`, (中文(简体) ), `docs`, (中文(简体) ), `sheets`, (中文(简体) ), `slides`, (中文(简体) ), `calendar`, (中文(简体) ), `gmail`, (中文(简体) ), `contacts`

-   奥米 `GOOGLE_WORKSPACE_SERVICES` 完全实现所有服务
-   统一工具`create_file`, (中文(简体) ), `update_file`, (中文(简体) ), `get_file_content`要求 `drive`, (中文(简体) ), `docs`, (中文(简体) ), `sheets`,以及 `slides`
-   当您限制服务时, 认证时只请求 OAuth 范围 。 如果您更改了启用的服务, 请重新认证以更新授予的范围 .

见 [高级配置](https://npmcn.com/package/%40dguido/google-workspace-mcp/docs/ADVANCED.md) 用于命名配置文件、多账户设置和环境变量.

## 可用工具

### 驱动器(29个工具)

`search` `listFolder` `createFolder` `createTextFile` `updateTextFile` `deleteItem` `renameItem` `moveItem` `copyFile` `getFileMetadata` `exportFile` `shareFile` `getSharing` `removePermission` `listRevisions` `restoreRevision` `downloadFile` `uploadFile` `getStorageQuota` `starFile` `resolveFilePath` `batchDelete` `batchRestore` `batchMove` `batchShare` `listTrash` `restoreFromTrash` `emptyTrash` `getFolderTree`

### 谷歌文档( 8个工具)

`createGoogleDoc` `updateGoogleDoc` `getGoogleDocContent` `appendToDoc` `insertTextInDoc` `deleteTextInDoc` `replaceTextInDoc` `formatGoogleDocRange`

### Google 工作表( 7个工具)

`createGoogleSheet` `updateGoogleSheet` `getGoogleSheetContent` `formatGoogleSheetCells` `mergeGoogleSheetCells` `addGoogleSheetConditionalFormat` `sheetTabs`

### 谷歌幻灯片(10个工具)

`createGoogleSlides` `updateGoogleSlides` `getGoogleSlidesContent` `formatSlidesText` `formatSlidesShape` `formatSlideBackground` `createGoogleSlidesTextBox` `createGoogleSlidesShape` `slidesSpeakerNotes` `listSlidePages`

### 日历(7个工具)

`listCalendars` `listEvents` `getEvent` `createEvent` `updateEvent` `deleteEvent` `findFreeTime`

### Gmail( 14个工具)

`sendEmail` `draftEmail` `readEmail` `searchEmails` `deleteEmail` `modifyEmail` `downloadAttachment` `listLabels` `getOrCreateLabel` `updateLabel` `deleteLabel` `createFilter` `listFilters` `deleteFilter`

### 联系人(6个工具)

`listContacts` `getContact` `searchContacts` `createContact` `updateContact` `deleteContact`

### 统一(3个工具)

`createFile` `updateFile` `getFileContent`

[完整 API 参考](https://npmcn.com/package/%40dguido/google-workspace-mcp/docs/API.md)

## 解决问题

### "没有找到授权证书"

设定 `GOOGLE_CLIENT_ID` 财务报告和审定财务报表 `GOOGLE_CLIENT_SECRET` 在您的 MCP 配置中嵌入 vars, 或者保存您的证书文件到 `~/.config/google-workspace-mcp/credentials.json`。 。 。 .

### "认证失败"或浏览器不打开

确保证书类型为"Desktop app"(不是"Web应用程序"). 服务器使用由OS指定的等离子端口,因此不需要特定的端口.

### "托肯斯过期"或"无效赠款"

"测试"状态中的Apps在7天后就过期了. 复试:

```bash
rm ~/.config/google-workspace-mcp/tokens.json
npx @dguido/google-workspace-mcp auth
```

**为了避免每周重新校正:** 发布您的 OAuth app (参见 [避免托肯过期](https://npmcn.com/package/%40dguido/google-workspace-mcp/#readme-avoiding-token-expiry) 页:1.

### “ API 未启用 ”

启用缺失的 API [谷歌云控台](https://console.cloud.google.com/) > APIs & Services > 图书馆.

### “ Login required ” 即使带有有效的符号

应用程序访问权限 : [谷歌账户权限](https://myaccount.google.com/permissions),明确的标志, 和重新认证.

[全部解决问题指南](https://npmcn.com/package/%40dguido/google-workspace-mcp/docs/TROUBLESHOOTING.md)

## 警卫

-   RFC 8252 符合 OAuth 2.0 与 PKCE (代码交换的密钥)
-   仅循环验证服务器(127.0.0.1)
-   CSRF 保护的国家参数
-   自动刷新令牌
-   以 0600 权限存储的托肯
-   所有处理都发生在本地
-   从不向版本控制输入证书或令牌

## 避免托肯过期

"测试"状态中的OAuth Apps在7天后自动失效. 为了避免每周重新校正:

### 备选案文1:公布您的 OAuth app(建议)

1.  转到 [谷歌云控台](https://console.cloud.google.com/) > APIS & 服务 > OAuth 同意屏幕
2.  点击"PUBLISH AP"
3.  个人使用,不需要完成Google的验证程序
4.  已发布应用程序在被明确取消之前保持符号有效

**说明:** Publishing将您的应用程序提供给任何Google用户,但由于您控制了OAuth证书,只有您可以认证.

### 备选案文2:使用内部应用程序(仅工作空间)

如果您有 Google 工作空间账户 :

1.  在 OAuth 同意屏幕上将用户类型设定为“ Internal ”
2.  内部应用不会过期 不需要出版

### 监测托肯时代

使用 `get_status` 检查标志年龄。 超过6天的托肯自动显示警告.

## 发展

```bash
npm install
npm run build    # Compile TypeScript
npm run check    # typecheck + lint + format check
npm test         # Run tests
```

见 [贡献指南](https://npmcn.com/package/%40dguido/google-workspace-mcp/CONTRIBUTING.md) 项目结构和发展工作流程.

## 来源

这个项目是对 [piotr-agier/谷歌驱动器](https://github.com/piotr-agier/google-drive-mcp),由Piotr Agier创建.

## 许可证

MIT - 详情见LICENSE文件.

## 常见问题

### @dguido/google-workspace-mcp 是什么？

Google 工作空间 MCP 服务器 - 模式上下文协议服务器,通过 MCP 客户端,例如 Claude 桌面,提供安全访问 Google Drive, Docs, Sheets, Slies, Calendar 和 Gmail 的功能

### 如何安装 @dguido/google-workspace-mcp？

在项目目录运行 npm install @dguido/google-workspace-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 google-workspace-mcp，可以用 npx google-workspace-mcp 直接运行。

### @dguido/google-workspace-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dguido\_\_google-workspace-mcp 是否存在。

### @dguido/google-workspace-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dguido/google-workspace-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dguido/google-workspace-mcp 可以商用吗？

@dguido/google-workspace-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dguido/google-workspace-mcp 的下载量有多少？

根据 npm 官方下载统计，@dguido/google-workspace-mcp 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,743 次，日均约 91 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dguido/google-workspace-mcp 还在维护吗？

最新版本 3\.4\.4 发布于 2026/02/23（8 个月前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/01/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。