内容
# Google Workspace MCP 服务器
一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，允许 Claude 访问 Google Workspace — 包括 Gmail、日历、Drive、联系人、表格、文档、幻灯片、任务等，并通过 [gws CLI](https://github.com/googleworkspace/cli) 提供 100 多个 API。
## 工具列表
| 服务 | 工具 | 操作 |
| --- | --- | --- |
| **Gmail** | 10 | 发送、回复、转发、读取、搜索、列出、创建草稿、更新草稿、标记已读、保存附件到 Drive |
| **日历** | 6 | 列出事件、获取事件、创建、更新、删除、空闲/忙碌 |
| **联系人** | 7 | 搜索、获取、列出、创建、更新、删除、目录搜索 |
| **Drive** | 3 | 搜索、读取文件、创建文件夹 |
| **表格** | 5 | 读取、更新、追加、创建、删除 |
| **文档** | 5 | 获取、写入、批量更新、创建、删除 |
| **幻灯片** | 4 | 获取、创建、批量更新、删除 |
| **任务** | 6 | 列出任务列表、列出任务、创建、更新、完成、删除 |
| **通用** | 1 | `gws_run` — 适用于上述未涵盖的任何 GWS API 的备用工具 |
| **身份验证** | 1 | OAuth 登录和状态 |
**共计 48 个工具。** 所有工具都支持共享（团队）Drive。
### 关键工具详情
**gmail_create_draft / gmail_update_draft** — 创建或替换 Gmail 草稿。从结构化参数（收件人、主题、正文、抄送、密送）和 base64url 编码中构造 RFC 2822 MIME 消息。`gmail_update_draft` 自动保留线程 — 如果未提供 `thread_id`，则在替换消息之前获取现有的草稿线程 ID。
**gmail_mark_read** — 通过删除 UNREAD 标签将消息标记为已读。还支持通过 `add_labels` 和 `remove_labels` 数组添加/删除任意标签（STARRED、IMPORTANT 等）。始终删除 UNREAD，无论其他标签更改如何。
**gmail_save_attachment_to_drive** — 从 Gmail 中获取附件并直接上传到 Drive 服务器端。没有 base64 数据流经对话。使用 try/finally 确保异步文件 I/O 和临时文件清理。
**drive_search** — 搜索个人和共享 Drive。支持完整的 [Drive 查询语法](https://developers.google.com/drive/api/guides/search-files)，包括文件夹父项、mimeType 过滤器和名称匹配。
**drive_create_folder** — 在 Drive 中创建文件夹，可选地在父文件夹内。
**drive_read_file** — 按文件 ID 读取 Drive 中任何文件的文本内容。按 mimeType 路由：
- Google Docs → 纯文本提取
- Google Sheets → 行/列数据（A1:Z1000）
- Google Slides → 具有占位符映射和文本的幻灯片结构
- Office 格式（.docx、.xlsx、.pptx）→ 服务器端转换为原生 Google 格式，读取转换后的副本，然后删除临时副本（通过 try/finally 确保清理）
- 纯文本 / CSV（`text/plain`、`text/csv`）→原始内容获取
- 不支持的类型（PDF、图像等）→ 返回 `{ error: "Unsupported file type: <mimeType>" }`
**docs_get** — 三种模式：
- `text`（默认）：带有 `[image:<id>]` 占位符的纯文本，适用于阅读/摘要
- `index`：带有 startIndex/endIndex 字符位置和内联对象引用的文本，用于位置编辑前
- `full`：原始 API 响应，用于调试或样式操作
所有模式都包含 `inlineObjects` 元数据映射（contentUri、size、margins、crop、border），当存在图像时。
**docs_create / sheets_create** — 返回仅包含必需字段的精简响应：
- docs_create → `{ documentId, title }`
- sheets_create → `{ spreadsheetId, title, spreadsheetUrl }`
**slides_get / slides_create** — 返回精简的响应（无母版、布局、几何形状、样式）。每个幻灯片都包含：
- `placeholder_map`：将标准类型（TITLE、BODY、SUBTITLE）映射到 objectIds
- `elements`：所有形状 — 包括标准占位符和自定义文本框
- 空占位符被包含，以便调用者在创建后立即插入文本，无需冗余的获取调用
**sheets_read** — 返回规范化的数据：
- `columnCount` 从最宽的行导出（正确处理空的前导行）
- 所有行都填充到统一的列数，并带有空字符串
**sheets_append** — 使用直接 Sheets API（`spreadsheets.values.append`）保留 2D 数组结构。每个内部数组都成为一个单独的行。
**docs_write** — 使用 batchUpdate API 和 insertText，正确处理换行符、破折号和 unicode 字符。
**gws_run** — 适用于任何未被专用工具涵盖的 Google Workspace API 的备用工具。接受服务、资源、方法、参数和 JSON 正文。仅在没有专用工具时使用。
## 安装（扩展 — Claude Desktop）
### 1. 创建 Google Cloud 项目
前往 [Google Cloud Console](https://console.cloud.google.com/) 并创建一个新项目（或使用现有项目）。
### 2. 启用 Google Workspace API
在您的项目中启用您计划使用的每个 API。点击以下链接并在每个页面上点击 **启用**：
- [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
- [Google Calendar API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
- [Google Drive API](https://console.cloud.google.com/apis/library/drive.googleapis.com)
- [Google Docs API](https://console.cloud.google.com/apis/library/docs.googleapis.com)
- [Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com)
- [Google Slides API](https://console.cloud.google.com/apis/library/slides.googleapis.com)
- [People API](https://console.cloud.google.com/apis/library/people.googleapis.com)（用于联系人）
- [Tasks API](https://console.cloud.google.com/apis/library/tasks.googleapis.com)
### 3. 配置 OAuth 同意屏幕
前往 [OAuth 同意屏幕](https://console.cloud.google.com/apis/credentials/consent)：
1. 选择 **外部** 用户类型
2. 填写应用名称（例如“Google Workspace CLI”）和您的电子邮件
3. 保存并继续所有屏幕
4. 在 **测试用户** 下，点击 **添加用户** 并添加您的 Google 账户电子邮件
### 4. 创建 OAuth 凭证
前往 [凭证](https://console.cloud.google.com/apis/credentials)：
1. 点击 **创建凭证** → **OAuth 客户端 ID**
2. 应用类型：**桌面应用**
3. 点击 **创建**
4. 复制 **客户端 ID** 和 **客户端密钥**
### 5. 配置 OAuth 凭证
```bash
cp .env.example .env
```
打开 `.env` 并填写您在上一步骤中获得的客户端 ID 和客户端密钥。
### 6. 构建扩展
```bash
pnpm install
pnpm run build
pnpm run build:extension
```
这会生成 `google-workspace-mcp.mcpb`。
### 7. 在 Claude Desktop 上安装
打开 Claude Desktop → 设置 → 扩展 → 从文件安装 → 选择 `google-workspace-mcp.mcpb`。
当扩展程序首次加载时，会自动打开一个浏览器窗口用于 Google OAuth 登录。登录并授权应用。之后，所有工具都已准备好使用。
> **注意：** 如果您的应用处于测试模式（未经验证），您会看到“Google hasn't verified this app”警告。点击 **高级** → **继续前往 \<应用名称>（不安全）** 以继续。这对于个人使用是安全的。
## 安装（HTTP 服务器 — Claude Code / 独立）
### 1. 完成上述步骤 1-5
### 2. 安装和构建
```bash
pnpm install
pnpm run build
```
### 3. 身份验证
使用步骤 5 中的环境变量，运行：
```bash
./bin/gws-aarch64-apple-darwin/gws auth login -s drive,gmail,sheets,calendar,docs,slides,people,tasks
```
### 4. 启动服务器
```bash
node server/index.js
```
MCP 服务器在 `http://localhost:39147/mcp` 上启动（可使用 `PORT` 环境变量覆盖）。
### 5. 连接 Claude Code
```bash
claude mcp add google-workspace --transport http http://localhost:39147/mcp
```
或将以下内容添加到 Claude Desktop MCP 配置中：
```json
{
"mcpServers": {
"google-workspace": {
"type": "streamable-http",
"url": "http://localhost:39147/mcp"
}
}
}
```
## 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `PORT` | `39147` | HTTP 服务器端口 |
| `GWS_OAUTH_CLIENT_ID` | — | OAuth 客户端 ID |
| `GWS_OAUTH_CLIENT_SECRET` | — | OAuth 客户端密钥 |
## 架构
```
src/
├── create-server.ts # 共享 MCP 服务器工厂（接受可选的每个会话客户端）
├── extension.ts # Stdio 入口点（.mcpb 扩展，在启动时自动身份验证）
├── index.ts # HTTP 入口点（StreamableHTTP，/health 和 /mcp 端点）
├── gws-client.ts # gws CLI 二进制文件的包装器，DEFAULT_SERVICES 常量
└── tools/
├── response.ts # 响应帮助程序（JSON 格式化，900KB 截断）
├── auth.ts # OAuth 登录（基于浏览器，无需 gcloud）
├── gmail.ts # Gmail 工具（草稿，标记已读，附件到 Drive）
├── calendar.ts # 日历工具
├── contacts.ts # 联系人/People API 工具
├── drive.ts # Drive 工具（搜索，读取文件，创建文件夹）
├── sheets.ts # 表格工具（规范化读取，直接 API 追加）
├── docs.ts # 文档工具（文本/索引/完整模式，内联图像元数据）
├── slides.ts # 幻灯片工具（精简响应，占位符映射）
├── tasks.ts # Google 任务工具（列表，CRUD，完成）
├── generic.ts # 通用 gws_run 备用
└── index.ts # 工具注册表（扁平映射<名称，处理程序>）
```
服务器包装 [`gws` CLI](https://github.com/googleworkspace/cli) 二进制文件，该二进制文件处理 OAuth 令牌管理和 API 发现。每个工具要么使用 `client.helper()` 进行高级别 CLI 命令，要么使用 `client.api()` 进行直接 Google API 调用。
扩展（`extension.ts`）通过 stdio 运行适用于 Claude Desktop `.mcpb` 包。HTTP 服务器（`index.ts`）作为独立进程运行适用于 Claude Code 或其他 MCP 客户端。两者共享相同的 `createMcpServer()` 工厂。
### 关键实现细节
- **共享驱动器支持**：所有 Drive API 调用都包含 `supportsAllDrives: true`（并且 `includeItemsFromAllDrives: true` 用于列表操作），以便可以访问团队驱动器上的文件
- **沙盒兼容性**：设置 `cwd: os.tmpdir()` 和 `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` 以适应 Claude Desktop 的只读文件系统
- **OAuth 凭证**：从环境变量读取，备用使用捆绑的 `oauth.json`（通过 `scripts/build-extension.sh` 在构建时注入）
- **自动身份验证**：扩展程序在启动时检查身份验证状态和范围覆盖，如果需要，打开浏览器进行 OAuth 登录（非阻塞 — MCP 服务器立即启动）
- **X-User-Token 支持**：HTTP 服务器接受 `X-User-Token` 头以创建具有预先获得的访问令牌的每个会话客户端（通过 `GOOGLE_WORKSPACE_CLI_TOKEN` 环境变量）
- **响应截断**：所有响应都限制在 900KB 以内，以保持在上下文限制内
- **上下文优化**：docs_get、slides_get 和 sheets_read 积极地剥离元数据以最小化上下文使用。docs_get 文本模式将 ~50KB API 响应减少到 ~2-3KB。slides_get 剥离了母版/布局/几何形状/样式。sheets_read 使用仅值 API 端点。
- **内联图像元数据**：docs_get 包含具有图像元数据（contentUri、size、margins）的 `inlineObjects` 映射，而不嵌入实际图像字节
- **幻灯片修剪**：从 API 响应中剥离了母版、布局、几何形状和样式 — 只返回 objectIds、占位符类型和文本内容
- **Office 文件读取**：`drive_read_file` 复制 Office 文件，并使用显式目标 mimeType 触发服务器端转换，读取本机副本，然后删除它（通过 try/finally 确保清理）
- **不支持类型保护**：`drive_read_file` 仅为 `text/plain` 和 `text/csv` 获取原始内容 — 所有其他非本机类型都返回干净的错误而不是二进制数据
- **平台支持**：macOS（arm64，x64），Linux（x64），Windows（x64）
## 开发
```bash
pnpm run dev # 监视模式 — 在更改时重新编译
```
## 许可证
MIT
