google-drive

Google Drive MCP Server

面向 Workspace 的强大编辑 MCP——支持公式的 Sheets、完整的 Slides 编辑，以及 Claude.ai 只读连接器刻意不提供的共享云端硬盘审计。

涵盖 Drive、Docs、Sheets、Slides、GWS 管理和聚合功能的 98 个工具。通过 Service Account + Domain-Wide Delegation 实现组织级自动化。具备 GWS 感知能力——Workspace 账户会自动解锁相应功能。

它有哪些独到之处

• 深入编辑 Sheets — 图表、条件格式、受保护范围、命名范围、数据验证、边框、合并、排序、查找/替换、公式，以及针对 CJK 标签页名称的 A1 引号加倍处理。第一方 Workspace 连接器会将 Sheets 读取为 CSV，公式无法保留。
• 完整编辑 Slides — 演示文稿、幻灯片、形状、表格、图片和格式。连接器完全不支持。
• 共享云端硬盘管理工具 — list-shared-drives、get-shared-drive、create-shared-drive、列出/共享/移除权限、文件活动、标签和审批。连接器刻意不开放 Workspace 治理功能。
• 3 种身份验证模式 — OAuth2（个人或 GWS）、Service Account + Domain-Wide Delegation（组织级）、Application Default Credentials（自动检测）。
• 聚合工具 — audit-shared-drive-permissions（审计单个共享云端硬盘）+ audit-external-shares（跨云端硬盘 / My-Drive 审计，并查看外部域名集中度排名）、summarize-spreadsheet（元数据 + 各标签页样例 + 命名范围）、summarize-doc（文件 + 内容 + 权限 + 评论）。
• MCP 提示词（3 个）— cleanup-shared-with-me、analyze-doc-structure、bulk-format-spreadsheet。
• 具备 GWS 感知能力 — capabilities.ts 会在启动时检测账户类型；个人账户调用仅限 GWS 的工具时，会收到明确错误，而不是难以理解的 403 错误。

试试这 5 个提示词

将服务连接到 Claude Desktop 或 Claude Code，然后粘贴以下任意提示词：

1. 审计共享云端硬盘权限 — “审计我所有共享云端硬盘中的外部共享。列出有权访问任何内容的 us-all.co.kr 以外的人员。按云端硬盘分组，并按访问级别排序。”
2. 批量设置条件格式 — “在我云端硬盘中每个 sales-* 电子表格的 amount 列应用以下条件格式：小于 0 时为红色，0–100 时为黄色，大于 100 时为绿色。”
3. 根据 Doc 大纲创建 Slides — “将这份 Google Doc 的大纲转换为 12 张幻灯片：标题页，然后每个 H2 对应 1 张幻灯片，并包含 H3 项目符号，最后以问答页结束。使用公司模板。”
4. 分析 Doc 结构 — “分析这份 Doc 的结构：标题层级、内部与外部链接的有效性、图片替代文本覆盖情况。提出 3 项具体改进建议。”
5. 清理与我共享的文件 — “查找 180 天以前与我共享、且我从未打开过的文件。列出文件及其共享者、最后修改时间，并猜测是否应该保留。”

何时使用此工具或其他替代方案

	Anthropic 官方 Workspace 连接器	taylorwilsdon/google_workspace_mcp	xing5/mcp-google-sheets	@us-all/google-drive-mcp（本工具）
Stars / 可用性	不适用（Claude.ai 内置，2026 年 2 月）	2.3K★	836★	—
范围	Drive 读取 + Sheets-as-CSV 读取	Gmail+Calendar+Drive+Docs+Sheets+Slides+Forms+Chat+Tasks+Contacts+Apps Script	仅 Sheets	Drive + Docs + Sheets + Slides + GWS 管理
Sheets 公式编辑	❌（CSV 往返会丢失公式）	✅ 基础	✅ 专业	✅ 深度（图表/条件格式/命名范围）
Slides 编辑	❌	✅	❌	✅ 深度
共享云端硬盘管理	部分支持	✅	❌	✅ 深度
文件夹操作	❌	✅	❌	✅
聚合工具	❌	❌	❌	✅ summarize-spreadsheet、summarize-doc、audit-external-shares
MCP 提示词	❌	❌	❌	✅ 4 个
身份验证模式	托管 OAuth	OAuth + SA + 无状态	SA / OAuth / ADC	OAuth + SA + DWD + ADC
传输方式	不适用（仅限 Claude.ai）	stdio + HTTP	stdio	stdio

如果要在 Claude.ai 中零配置读取 Drive，请使用官方连接器。如果需要完整的 Workspace 功能（Gmail / Calendar / Forms 等），请使用 taylorwilsdon。如果需要对 Drive + Docs + Sheets + Slides 进行高级编辑、管理共享云端硬盘，以及执行连接器无法完成的批量操作，请使用本服务。

安装

Claude Desktop

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "@us-all/google-drive-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "<your-client-id>",
        "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
        "GOOGLE_REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

Claude Code

claude mcp add google-drive -s user -- npx -y @us-all/google-drive-mcp

（请单独设置环境变量，或在 .mcp.json 中设置。）

Docker

docker run --rm -i --env-file .env ghcr.io/us-all/google-drive-mcp-server

从源代码构建

git clone https://github.com/us-all/google-drive-mcp-server.git
cd google-drive-mcp-server && pnpm install && pnpm build
node dist/index.js

身份验证设置

OAuth2（个人或 GWS）

1. Google Cloud Console → 创建项目
2. 启用 Drive API、Docs API、Sheets API、Slides API、Drive Activity API、Drive Labels API
3. 创建 OAuth2 凭据（Desktop App）
4. 获取刷新令牌（使用 OAuth2 playground 或自行设置流程）
5. 设置 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REFRESH_TOKEN

服务账号 + 全网域委派（组织规模）

1. 在 Google Cloud Console 中创建服务账号
2. 下载 JSON 密钥
3. Workspace Admin Console → Security → API Controls → Domain-Wide Delegation → 添加服务账号的 Client ID，并授予所需范围
4. 设置 GOOGLE_SERVICE_ACCOUNT_KEY_PATH 和 GOOGLE_IMPERSONATE_USER

应用默认凭据（零配置）

gcloud auth application-default login --client-id-file=client_secret.json --scopes=... — 启动时自动检测。支持 Windows ADC 路径（%APPDATA%\gcloud\）。

配置

变量	必填	默认值	说明
GOOGLE_CLIENT_ID	OAuth2	—	OAuth2 客户端 ID
GOOGLE_CLIENT_SECRET	OAuth2	—	OAuth2 客户端密钥
GOOGLE_REFRESH_TOKEN	OAuth2	—	OAuth2 刷新令牌
GOOGLE_SERVICE_ACCOUNT_KEY_PATH	SA	—	服务账号 JSON 密钥的路径
GOOGLE_IMPERSONATE_USER	❌	—	要模拟的 GWS 用户邮箱（仅 SA）
GOOGLE_DRIVE_ALLOW_WRITE	❌	false	设置为 true 以启用更改操作
GOOGLE_DRIVE_SCOPES	❌	只读 Drive Activity + Docs 范围（或启用写入时使用更广泛的 Drive/Docs 范围）	以逗号分隔的 OAuth 范围覆盖值
GD_TOOLS	❌	—	以逗号分隔的类别允许列表。最能节省令牌。
GD_DISABLE	❌	—	以逗号分隔的类别拒绝列表。设置 GD_TOOLS 时将忽略此项。
MCP_TRANSPORT	❌	stdio	设置为 http 以启用 Streamable HTTP 传输方式
MCP_HTTP_TOKEN	有条件	—	Bearer 令牌。MCP_TRANSPORT=http 时必填
MCP_HTTP_PORT	❌	3000	HTTP 监听端口
MCP_HTTP_HOST	❌	127.0.0.1	HTTP 绑定主机（localhost 会自动启用 DNS 重绑定防护）
MCP_HTTP_SKIP_AUTH	❌	false	跳过 Bearer 身份验证 — 例如，部署在负责身份验证的反向代理之后时

类别（7 个）：drive、sheets、docs、slides、shared-drives、labels、approvals。另有始终启用的 meta。

当 MCP_TRANSPORT=http 时：POST /mcp（Bearer 身份验证的 JSON-RPC）+ GET /health（公开存活状态检查）。

Token 效率

场景	工具	Schema 令牌数	相较默认值
默认（所有类别）	96	18,400	—
常见（GD_TOOLS=drive,docs,sheets）	68	13,700	−25%
精简（GD_TOOLS=drive）	25	4,000	−78%

在 list-files/get-file/sheets-get-spreadsheet/docs-get-document 上使用 extractFields 投影（默认包含 tabsCount、rowCount、columnCount、locale、timeZone）。list-files 的精简默认设置可缩减约 80%（移除 capabilities 这个含 40 个布尔值的对象，以及 contentRestrictions）。

GWS 检测

capabilities.ts 会在启动时通过 about.get() 和域名检查来检测账户类型：

功能	个人账户	GWS Standard+	GWS Enterprise
文件增删改查 / 搜索 / 导出	✅	✅	✅
Docs / Sheets / Slides 编辑	✅	✅	✅
评论与修订	✅	✅	✅
Drive 活动记录	✅	✅	✅
共享云端硬盘	—	✅	✅
标签（分类）	—	✅	✅
审批	—	✅	✅
全域委派	—	✅	✅

个人账户使用 GWS 专属工具时会抛出 GWSFeatureError，并显示清晰的错误消息，不会出现难以理解的 403 错误。

MCP 提示词（4 个）

可通过 MCP prompts/list 使用的工作流模板：

• audit-shared-drive-permissions — 全域审计外部共享情况；标记访问级别异常项。
• cleanup-shared-with-me — 查找长期未访问的过期共享内容，并建议清理。
• analyze-doc-structure — 分析标题层级、链接有效性和替代文本覆盖情况。
• bulk-format-spreadsheet — 在多个工作表/标签页中应用一致的格式。

MCP 资源

基于 URI 的只读访问：

• gdrive://file/{fileId}
• gdrive://spreadsheet/{spreadsheetId}
• gdrive://document/{documentId}
• gdrive://presentation/{presentationId}
• gdrive://folder/{folderId}
• gdrive://shared-drive/{driveId}（需启用 GWS）
• gdrive://about/me

工具（98 个）

共 7 个类别。使用 search-tools 在运行时查找工具；完整列表已折叠如下。

类别	工具数
Sheets（数据 / 结构 / 格式 / 高级功能）	30
Drive（文件 / 搜索 / 文件夹 / 权限 / 导出 / 评论 / 修订 / 活动记录）	24
Slides（演示文稿 / 幻灯片管理 / 内容 / 格式）	20
Docs（文档 / 编辑 / 格式 / 元素）	13
GWS 专属（共享云端硬盘 / 标签 / 审批 / 审计）	9
聚合（summarize-spreadsheet、summarize-doc、audit-external-shares）	3
元数据（search-tools）	1

完整工具列表

Drive（24 个）

get-about、list-files、get-file、read-file、create-file、update-file、copy-file、delete-file、search-files、create-folder、move-file、get-folder-tree、list-permissions、share-file、remove-permission、export-file、get-download-link、list-comments、get-comment、create-comment、resolve-comment、list-revisions、get-revision、get-activity

Google Docs（13 个）

文档：docs-get-document、docs-create-document、docs-get-content、docs-list-tabs 编辑：docs-insert-text、docs-delete-range、docs-replace-text、docs-batch-update 格式：docs-format-text、docs-format-paragraph 元素：docs-insert-table、docs-insert-image、docs-insert-page-break

### Google 表格（30） **数据**：`sheets-get-spreadsheet`、`sheets-get-values`、`sheets-batch-get-values`、`sheets-update-values`、`sheets-batch-update-values`、`sheets-append-values`、`sheets-clear-values`、`sheets-batch-clear-values`、`sheets-create-spreadsheet`、`sheets-manage-sheets` **结构**：`sheets-insert-dimension`、`sheets-delete-dimension`、`sheets-duplicate-sheet`、`sheets-copy-sheet-to`、`sheets-copy-paste`、`sheets-sort-range`、`sheets-find-replace` **格式设置**：`sheets-format-cells`、`sheets-update-borders`、`sheets-merge-cells`、`sheets-unmerge-cells`、`sheets-auto-resize`、`sheets-resize-dimensions` **高级功能**：`sheets-set-data-validation`、`sheets-add-conditional-format`、`sheets-add-chart`、`sheets-delete-chart`、`sheets-add-protected-range`、`sheets-delete-protected-range`、`sheets-manage-named-range`

Google 幻灯片（20）

演示文稿：slides-get-presentation、slides-create-presentation、slides-duplicate-presentation 幻灯片管理：slides-get-slide、slides-add-slide、slides-delete-slide、slides-move-slide、slides-duplicate-slide 内容：slides-insert-text、slides-replace-text、slides-insert-text-box、slides-insert-image、slides-insert-table、slides-update-table-cell、slides-insert-shape 格式设置：slides-format-text、slides-format-shape、slides-resize-element、slides-set-slide-background、slides-batch-update

仅限 GWS（9）

list-shared-drives、get-shared-drive、create-shared-drive、audit-shared-drive-permissions、list-file-labels、apply-label、remove-label、list-approvals、get-approval

聚合工具

summarize-spreadsheet、summarize-doc、audit-external-shares

audit-external-shares 是仅限 GWS 的 audit-shared-drive-permissions 的补充：它会检查调用者可访问的所有语料库（个人账号则仅检查“我的云端硬盘”），并提供外部域名集中度视图。

元工具

search-tools — 按关键字查询其他工具；始终启用。

架构

Claude → MCP stdio → src/index.ts
                      ├── config.ts (OAuth2 / SA / ADC)
                      ├── capabilities.ts (Personal vs GWS detect)
                      ├── client.ts (Google API auth)
                      └── tools/{files,search,folders,permissions,export,comments,revisions,
                                  about,activity,docs,sheets,slides,shared-drives,labels,approvals,
                                  aggregations}.ts
                                       ↓
                              Drive API v3 / Docs API v1 / Sheets API v4 /
                              Slides API v1 / Drive Activity API v2 / Drive Labels API v2

基于 @us-all/mcp-toolkit 构建：

• extractFields — 高效利用令牌的响应投影
• aggregate(fetchers, caveats) — 为 summarize-doc 提供的扇出辅助工具
• createWrapToolHandler — Google 查询字符串 key=... 脱敏 + WriteBlockedError / GWSFeatureError 透传 + Google API 错误提取
• search-tools 元工具

每次调用 Drive API 时都会传入 supportsAllDrives: true，因此共享云端硬盘可直接使用。

技术栈

Node.js 22+ • TypeScript strict ESM • pnpm • @modelcontextprotocol/sdk • googleapis（Drive v3 / Docs v1 / Sheets v4 / Slides v1 / Activity v2 / Labels v2）• zod • dotenv • vitest。

局限性

• 审批 API — googleapis SDK 没有类型化绑定；使用带有身份验证标头提取功能的原始 fetch。
• search-files — 会自动将纯文本包装为 fullText contains '...'；高级搜索请直接传入 Drive 查询语法。

许可证

MIT