Google Drive

google-drive-mcp

将 Google Drive 作为 MCP 工具。查找、整理、共享和移动文件，并追踪变更。

这是一个通过标准输入/输出使用 Model Context Protocol 的 Go 单文件二进制程序。它作为客户端的子进程在你自己的设备上运行，每个配置对应一个 Google 账号：查找文件并了解其所在位置及可见对象、整理文件夹、移动和复制文件、导入和导出内容、共享文件而不意外扩大访问权限、追踪变更，以及管理共享云端硬盘。

为什么选择 google-drive-mcp

文件存放在 Drive 中，而文件出现的大多数问题都与边界有关，而非内容本身：文件位于何处、哪些人已经可以查看、扩大共享范围实际会影响什么，以及自上次查看以来有哪些变更。此服务在这个边界上工作，不会越界——Doc、Sheet 或 Slides 演示文稿的内容应由基于这些 API 构建的服务处理；本服务会明确说明这一点，而不会通过导出内容来猜测。

它以你的身份运行，并使用你自己的 Google Cloud 项目，因此这里的任何内容都不依赖特定组织或账号。下方的每个工具都经过真实 Google Workspace 账号和测试所用的内存版 Drive 验证，其中也包括五个会永久删除内容的工具；这些测试在实时驱动程序创建并再次销毁的共享云端硬盘中运行。另有四种路径无法验证，因为每种都需要第二个账号或管理员才能测试：转移所有权、打开需要资源密钥的链接共享文件、尝试组织政策拒绝的共享，以及应用标签。docs/architecture.md 的 §17a 说明了每种情况的替代验证方式。

安装

go install github.com/mmedum/google-drive-mcp/v3/cmd/google-drive-mcp@latest

这会将二进制程序安装到 Go 的 bin 目录中，而该目录通常不在你的 PATH 中。如果下一条命令提示 command not found，可以使用完整路径，或将该目录添加一次：

"$(go env GOPATH)/bin/google-drive-mcp" --version    # check it landed
export PATH="$(go env GOPATH)/bin:$PATH"             # or add it to your shell profile

或者从最新版本下载经过签名的压缩包——适用于 amd64 和 arm64 的 Linux、macOS 和 Windows——并将二进制程序放到你的 PATH 中。每个压缩包都包含二进制程序、LICENSE 和本 README。你不必盲目信任任何发行版本：

# --ignore-missing, because checksums.txt covers every archive and you
# will have downloaded one of them.
sha256sum -c checksums.txt --ignore-missing

# checksums.txt is signed with a keyless Sigstore certificate tied to the
# release workflow's identity; the bundle carries the signature and the
# certificate together.
cosign verify-blob checksums.txt --bundle checksums.txt.bundle \
  --certificate-identity-regexp '^https://github.com/mmedum/google-drive-mcp' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And each archive carries build provenance naming the workflow and tag
# that produced it.
gh attestation verify google-drive-mcp_*.tar.gz --repo mmedum/google-drive-mcp

每个压缩包还附带 SBOM，因此你可以查看自己没有构建的二进制程序包含哪些内容。

Claude Desktop

每个版本还附带一个 .mcpb bundle。打开它，Claude Desktop 会安装 MCP 服务，并询问客户端配置中会包含的设置：你的 OAuth 客户端 JSON、配置文件、只读模式、破坏性操作开关、共享工具、下载和上传文件夹、最大下载大小、Workspace 标签和活动记录——无需编辑配置文件。永久删除和向组织外部共享（enable_destructive）、标签（labels）和活动记录（activity）默认关闭，除非你手动开启；只读模式下，破坏性操作开关不会注册任何功能。此 MCP 服务不会在调用前征求任何人的许可。Claude Desktop 会逐个批准工具，可选择“允许一次”或“始终允许”；设为始终允许的工具之后会直接运行，不再询问，因此除非需要使用相应工具，否则请保持开关关闭。

它支持 macOS、Windows 和 Linux，且每个平台都支持两种架构：macOS 使用通用二进制文件，Windows 使用 amd64，Linux 使用一个小型启动器，在启动时选择合适的二进制文件，因为 bundle 清单会为每个平台指定命令，却没有用于指定架构的键。其 SHA-256 值位于同一份经过签名的 checksums.txt 中。

此 bundle 不会为你登录。请同时安装二进制文件，并运行一次 google-drive-mcp login；bundle 会使用同一份凭据。标签和活动记录还需要使用会请求相应作用域的登录方式，例如 google-drive-mcp login --labels=true。Claude Code 不会安装 .mcpb 文件，因此请使用下面的命令。

设置 Google

你需要自己的 Google Cloud 项目和 OAuth 客户端。整个过程大约需要 5 分钟，google-drive-mcp doctor 会告诉你遗漏了哪一步。

1. 创建项目，访问 console.cloud.google.com。

2. 启用 Google Drive API：在项目的 API 和服务 → 库 中启用。

3. 配置 OAuth 同意屏幕。

   • 如果使用 Google Workspace 账号，请选择 内部。刷新令牌不会过期。
   • 如果使用个人账号，请选择 外部，保持 测试 状态，并将自己的邮箱地址添加为测试用户。Google 会在 7 天后使测试应用的刷新令牌过期，因此你需要大约每周重新运行一次 login。

4. 添加此 MCP 服务所需的作用域。 具体需要哪些作用域取决于运行方式，login 会准确请求配置所需的作用域——因此请添加你将使用的作用域；之后若启用某项功能，请重新运行 login。这些作用域都属于受限作用域，对于仅供自己使用且不会发布的应用，这没有问题。

   作用域	请求条件
   https://www.googleapis.com/auth/drive	始终请求，除非启用只读模式
   https://www.googleapis.com/auth/drive.readonly	设置 GDRIVE_READ_ONLY=true 时，用它代替上述作用域
   https://www.googleapis.com/auth/drive.labels	设置 GDRIVE_LABELS=true 时
   https://www.googleapis.com/auth/drive.labels.readonly	同时设置 GDRIVE_LABELS=true 和只读模式时
   https://www.googleapis.com/auth/drive.activity.readonly	设置 GDRIVE_ACTIVITY=true 时

   google-drive-mcp doctor 会指出令牌缺少哪些作用域；更改标志后，如果调用被拒绝，请运行此命令。

5. 创建凭据 → OAuth 客户端 ID → 桌面应用，然后下载 JSON。Web 应用客户端无法使用：此 MCP 服务采用 Google 为桌面应用说明的环回流程。

6. 将 JSON 放到 MCP 服务查找的位置，或指定其路径：

   mkdir -p ~/.config/google-drive-mcp
   cp ~/Downloads/client_secret_*.json ~/.config/google-drive-mcp/client_secret.json
   

7. 登录并检查：

   google-drive-mcp login
   google-drive-mcp doctor
   

login 会打开浏览器，通过 PKCE 在 127.0.0.1 接收回调，并将刷新令牌存储在操作系统密钥环（Secret Service、Keychain 或 Credential Manager）中。如果没有可用的密钥环，它会改用 0600 权限的文件，并告知你这一情况。logout 会向 Google 撤销令牌，并将其从本地删除。

通过 SSH 登录

回调会发送到远程主机的回环地址，而浏览器在本地，因此必须转发端口。端口是随机分配的，只有在等待登录时才会打印出来，所以请从打印出的 URL 中读取端口——它会以百分号编码的形式显示为 127.0.0.1%3A<port>——然后在另一个本地终端中运行：

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

然后在本地浏览器中打开该 URL。如果 ssh 提示 bind: Address already in use，请按 Ctrl-C 取消登录，然后重新启动以分配其他端口。

连接客户端

Claude Code

claude mcp add google-drive -- google-drive-mcp

Claude Desktop（claude_desktop_config.json）和 Cursor （.cursor/mcp.json）采用相同的格式：

{
  "mcpServers": {
    "google-drive": {
      "command": "google-drive-mcp",
      "env": {
        "GDRIVE_LOCAL_DIR": "/absolute/path/for/downloads"
      }
    }
  }
}

这三个客户端只传递 command、args 和 env，因此所有设置都是环境变量。

配置

每项设置都是一个 GDRIVE_* 环境变量，并有对应的标志。完整列表及默认值见 docs/configuration.md。以下设置会改变服务的整体行为：

变量	默认值	作用
GDRIVE_LOCAL_DIR	未设置	下载写入、上传读取的唯一目录。未设置意味着完全不进行文件传输。
GDRIVE_READ_ONLY	false	仅注册读取工具，并在登录时申请只读权限范围。
GDRIVE_SHARING	all	off 会取消注册共享工具，保留共享云端硬盘的限制、文件的下载和重新共享开关，以及文件夹的受限访问设置，避免这些限制被放宽；还会拒绝可能让更多人访问某项内容的移动操作，以及可能让比原件更多人访问的复制操作。
GDRIVE_ENABLE_DESTRUCTIVE	false	注册永久删除、清空垃圾箱及其他不可逆工具，以及可能将共享范围扩展到组织之外的共享方式：任何人均可访问的链接、整个网域、组织外的人员、新所有者，以及解除共享云端硬盘的网域限制。每次调用这些操作时仍须提供 confirm: true。

GDRIVE_REQUIRE_PROMPT 已在 3.0.0 中移除：服务不再向你询问任何内容。如果此项设置为除 false 以外的任何值，服务将拒绝启动，而不会悄然允许你要求其阻止的操作。

谁批准每次调用

每次调用都由 MCP 客户端批准；服务端不会自行询问你。claude.ai 和 Codex 会提示你批准标记为破坏性的工具：删除操作、四个会触及组织范围之外内容的工具、approve_file，以及会替换现有内容的写入操作（update_content、manage_revision、reply_comment 和 manage_labels）。VS Code 会提示你批准所有未标记为只读的工具，也就是所有写入工具，包括 download_file。在 Claude Code 中，无论你的规则如何，delete_file、empty_trash、delete_drive 和 share_by_link 每次调用都会询问；如果无法显示提示，则会拒绝这些操作：它们都无法撤销，而且每个操作都会越过单个项目的范围——跳过回收站、清空整个回收站或共享云端硬盘，或者向所有持有链接的人或整个域开放文件。对于其余操作，请在设置的 permissions.ask 下逐一列出你想批准的调用，并将 google-drive 替换为你为服务端指定的名称。例如，分享、发布、批准或删除的写入操作：

{
  "permissions": {
    "ask": [
      "mcp__google-drive__share_file", "mcp__google-drive__share_outside_organization",
      "mcp__google-drive__share_by_link", "mcp__google-drive__transfer_ownership",
      "mcp__google-drive__resolve_access_request", "mcp__google-drive__lift_drive_restriction",
      "mcp__google-drive__approve_file",
      "mcp__google-drive__delete_file", "mcp__google-drive__empty_trash",
      "mcp__google-drive__delete_drive", "mcp__google-drive__delete_revision",
      "mcp__google-drive__delete_comment"
    ]
  }
}

无论客户端做什么，以下规则都不会改变：

• 广泛分享有各自专用的工具。 share_file 只会向组织内部的指定个人和群组授予权限。面向所有人的链接、整个域、组织外部人员和新所有者分别使用各自的工具；这些工具只有在设置 GDRIVE_ENABLE_DESTRUCTIVE=true 后才会注册。外部人员指其域名不属于你账户的地址；在没有组织的个人 Google 账户中，所有地址都属于外部地址。
• 不会因省略设置而扩大权限。 如果移动、复制或关闭文件夹的受限访问权限会让任何持有链接的人、某个域或组织外部人员访问文件，系统就会拒绝操作，并说明涉及的对象。接受组织外部人员的访问请求也会被拒绝。
• 删除操作需要标志和 confirm: true。 默认通过移至回收站和恢复来移除内容；confirm: true 表示调用方确认其确实要执行这项删除，而不是表示你已批准。

工具

工具	功能
get_account	查看谁已登录、已使用的存储空间、此账号是否有共享云端硬盘，以及此服务的哪些工具已注册
get_file	查看单个文件的所有信息：类型、位置、链接、大小、所有者、谁可以查看、谁不能下载，以及你可以对它执行哪些操作
list_folder	查看文件夹内容的一页，或按预算限制查看其下的完整目录树
search_files	在“我的云端硬盘”、与您共享的文件和所有共享云端硬盘中查找文件，或在某个文件夹及其任意深度的子文件夹中查找
read_file	读取文件文本：将 Google 文档读取为 Markdown、将 Google 表格读取为 CSV、将 Word、Excel 或 PowerPoint 文件（或对应的 OpenDocument 文件）作为文本读取，将日志或源文件按原样读取；支持分段读取和继续读取
extract_text	读取 PDF 或图像中的文本：通过 Google OCR 识别，并临时复制为 Google 文档，之后再删除副本
download_file	将文件写入本地目录，下载时转换 Google 文档，并验证校验和
create_file	创建新的空白 Google 文件，或使用此处已有的文本创建文件；可选择转换
upload_file	上传本地文件，可一次完成，也可分块上传以便连接中断后继续
update_content	替换文件内容，同时保留其 ID、位置以及所有指向它的内容；如果 Markdown 文件中包含 Google 文档保留的评论，则拒绝丢弃这些评论
create_folder	创建新文件夹；除非允许，否则拒绝创建重名文件夹
update_file	重命名、添加说明、加星标、设置颜色、设置属性、限制下载和重新共享，或为文件夹授予有限访问权限
move_file	将一个或最多 50 个项目移至其他文件夹或共享云端硬盘；显示移动前后各自可访问的人，并支持试运行
copy_file	复制文件，可选择让 Google 将其导入为文档，从而读取 PDF 或扫描件中的文本；使用 recursive 可复制整个文件夹；显示原件和副本各自可访问的人
create_shortcut	在另一个文件夹中创建指向某个项目的快捷方式
trash_file	将项目移至回收站，可撤销
restore_file	将项目从回收站中取出，并说明它被还原到何处
list_permissions	查看谁可以访问某个项目，包括角色、到期时间，以及每项授权的来源
share_file	向组织内部的人员和群组授予或更改访问权限，并显示更改前后谁可以查看
unshare_file	撤销访问权限，或停用允许任何人打开文件的链接
list_drives	查看此账号可以访问的共享云端硬盘，以及此账号在每个硬盘中的可执行操作
manage_drive	创建、重命名、隐藏、取消隐藏或限制共享云端硬盘；绝不解除其网域限制
list_revisions	查看文件的版本历史记录，并显示 Google 对其未记录内容的说明
manage_revision	固定某个版本以便云端硬盘保留它，或取消固定当前版本；较旧版本一旦固定便会永久保留
list_changes	查看自某个时间点以来发生的更改，并获取下次使用的令牌
list_comments	查看文件上的评论串、回复，以及每条评论串是否仍未解决
add_comment	在任意文件（无论是否为 Google 文档）上发起评论串
reply_comment	回复评论串、解决或重新打开评论串，或编辑其中已有内容
list_access_requests	查看谁申请了文件访问权限，以及申请的权限内容
resolve_access_request	接受组织内部人员的申请，或拒绝任何申请，并显示处理前后谁可以查看文件
list_approvals	查看文件的审核：谁发起了审核、谁需要回复，以及是否正在等待你处理
manage_approval	请求他人审核文件、拒绝或撤回审核、对审核发表评论，或更改受邀审核者；还可选择内容更改是否重置审核
approve_file	批准指派给你的审核；批准后可能会永久锁定文件
另外 3 个工具只有在部署者启用相应功能后才会注册，因为每个工具都需要一个授权范围，否则该范围不会出现在同意屏幕上：将 GDRIVE_LABELS=true 时注册 list_labels 和 manage_labels，将 GDRIVE_ACTIVITY=true 时注册 list_activity。

工具	功能
list_labels	此账号可使用的 Workspace 标签，以及每个字段及其可取的值
manage_labels	为文件添加标签、设置或清除其字段，或移除标签
list_activity	查看文件或文件夹中所有内容发生了什么，以及发生时间

另外 9 个工具只有在设置 GDRIVE_ENABLE_DESTRUCTIVE=true 时才会注册，而且每次调用这些工具时都必须带上 confirm: true。其中 5 个会永久删除内容：delete_file、empty_trash、delete_drive、delete_revision 和 delete_comment。另外 4 个会将内容共享给组织之外的对象：share_by_link 会让任何拥有链接的人或整个网域都能访问文件；share_outside_organization 会授予组织外的某人访问权限；transfer_ownership 会将文件交给新所有者；lift_drive_restriction 会允许共享云端硬盘中的内容共享给组织外的对象。这 4 个工具还会要求提供要开放的对象名称，即 file_name 或 drive_name，因此客户端向你展示的待批准调用会指出具体文件或云端硬盘；如果名称与该对象不符，调用将被拒绝。

其中 3 个读取工具也提供资源，供通过挂载资源而非调用工具的客户端使用：gdrive://<id> 是文件文本，gdrive://<id>/meta 是文件说明，gdrive://<id>/children 是文件夹的第一页内容。引用中带斜杠的内容（路径、URL）必须进行百分号编码，因此请传入 ID。

与其他方案相比，它有 5 个不同之处：

• 首次调用即可使用共享云端硬盘。 每个请求都会携带 supportsAllDrives，列表包含所有云端硬盘中的项目；如果搜索结果不完整，也会明确说明，而不会悄悄少返回内容。
• ID 是唯一依据。 如果名称或路径匹配到多个项目，结果会标记为 [ambiguous]，并列出所有候选项。不会使用第一个匹配项。
• 始终显示位置。 云端硬盘中的名称并不唯一，因此每个结果都会指出文件所在的文件夹和云端硬盘。
• 文件只能在一个位置传输。 下载内容会保存到 GDRIVE_LOCAL_DIR，上传内容会从该目录读取；如果未设置此变量，则完全不会传输文件。目录之外的路径会被拒绝，包括符号链接。
• 共享操作清晰可见。 每次授予或撤销权限都会报告操作前后哪些人可以查看文件。公开链接、共享给组织外的对象和所有权转移各自使用独立工具，默认关闭，只有部署者启用后才可用。除非你明确要求，否则不会发送通知邮件；这与 API 自身的默认行为相反。

安全性

• 编辑 Google Doc、Sheet 或 Slides 演示文稿的内容。它通过 Google 的导出功能读取这些内容，并会说明这一点。在这里添加的评论会附加到文件，而非文件中的某个位置：要在 Doc、Sheet 或 Slides 演示文稿中固定评论，需要使用该类文件自身的 API，而此服务不会使用该 API。
• 删除 Google Docs 保存在 Markdown 文件中的评论。Docs 会就地编辑存储在 Drive 中的 .md 文件，并将在那里添加的评论写入文件自身的文本，而 Drive 的评论列表不会列出这些评论。除非设置了 allow_comment_changes，否则 update_content 会拒绝可能导致评论丢失的新内容。
• 在未收到要求时扩大访问权限。共享工具会先检查 capabilities.canShare，并显示文件共享前后的可见对象。未设置 GDRIVE_ENABLE_DESTRUCTIVE=true 时，这里的任何操作都无法将共享范围扩大到组织之外；移动或复制操作也绝不会扩大共享范围。只有在你要求时才会发送通知邮件。实际可以共享的对象由你所在组织的政策决定，Google 会在每次调用时强制执行该政策。
• 默认情况下，不可逆地销毁任何内容。默认操作仅限移至回收站和恢复；永久删除需要设置 GDRIVE_ENABLE_DESTRUCTIVE=true，并且调用时还需提供 confirm: true，因为已注册的工具迟早会被模型调用。没有批量删除或批量共享功能：每次调用仅处理一项，因此每次删除都需要明确批准。直接拒绝删除云端硬盘的顶层目录。唯一无需满足上述任一条件、就会被永久删除的内容，是 extract_text 在同一次调用中创建并移除的临时副本。
• 与 Google 以外的任何对象通信。附加凭据前，所有 URL 都会与 Google 自有主机的允许列表进行核验。不进行遥测，也不检查更新。
• 将任何私人信息写入日志。日志仅包含截断后的 ID、数量、字节数和延迟；绝不记录文件名、路径、地址、查询或内容。

工作原理

MCP client ──stdio──► google-drive-mcp
                       ├── tools      one handler per tool; shapes the reply
                       ├── service    the rules: addressing, sharing policy, confinement
                       ├── model      the server's view of a file, and what you may do to it
                       ├── render     the text a result is made of
                       ├── gapi       raw REST client for Drive, Drive Labels and Drive Activity
                       ├── gdrive     hand-written wire types, no generated client
                       ├── ref        ids, URLs and paths; resolves nothing over the network
                       └── auth       refresh token → access token

docs/architecture.md 介绍了设计、软件包布局、阶段计划，以及一份证据日志，记录哪些约定已根据 Google 官方参考资料核实，哪些后来被证实有误。docs/security.md 说明了它会访问哪些内容，以及有哪些限制。

获取帮助

如果遇到问题，请运行 google-drive-mcp doctor。它会检查凭据、已授予的范围以及 Google 实际返回的信息，并指出缺少的内容——首次运行时的大多数问题，都是因为未启用相应 API，或同意页面中没有你的账号。

google-drive-mcp status 会在不联系 Google 的情况下显示相同的设置信息；status --json 则会将其打印为一个 JSON 对象，供需要在启动此服务前判断其是否已获授权的脚本使用——应根据 credentials.resolved 字段进行判断。数据结构详见 docs/configuration.md。

如果这仍无法解释问题， 请提交 issue。切勿在其中粘贴文件 ID 或 URL、文件内容、client_secret.json 或令牌；请改为描述其特征。安全问题请通过 SECURITY.md 私下报告。

版本管理

工具名称、参数和输出结构在同一主版本内保持稳定。凡是需要你采取操作的变更——例如新增范围、再次执行 login，或更改客户端配置中的命令——都会在 CHANGELOG.md 中标记为 Breaking:；发布说明也由该文件生成。工具从默认功能移至功能标志后方，或从功能标志后方移至默认功能，都属于破坏性变更。

开发

make build     # the binary
make test      # race detector, per-package coverage floor
make check     # everything CI runs
make live      # drive the binary against the signed-in account, redacted

除非明确要求，否则 make live 不会执行任何更改：-write 和 docs/development.md 中的标志会启用写入操作。-transfer 会将临时文件永久交给另一个账号，此操作无法撤销，而且 Google 会向该账号发送电子邮件。

make check 是完成标准：gofmt、go vet、golangci-lint、 带有逐包覆盖率下限的竞态测试、govulncheck、许可证 检查、工作树泄漏检查、固定版本和错误类别门槛、API 覆盖率门槛（要求所有三个 API 的每个方法都有 记录在案的决策）、捆绑清单门槛（要求已提交的清单与打包器暂存的文件一致）、注册表门槛（要求已发布的条目符合 MCP 注册表在代码中强制执行的规则）、传输记录门槛（禁止任何驱动真实账号的程序绕过脱敏器 到达终端）、实时覆盖率门槛（要求对每个工具选项都作出决策，确定实时驱动程序是否会驱动该选项）、结果门槛（禁止根据请求而非响应撰写结果描述）、stdio 冒烟测试、与已发布工具界面的架构差异检查、过时检查（当本 README、文档或变更日志 与代码不一致时失败），以及一致性门槛（断言 make check 和 CI 运行相同的一组门槛）。

约定见 CONTRIBUTING.md；构建、测试 和发布说明见 docs/development.md。

文档

• docs/architecture.md — 设计、设计依据的证据 以及阶段计划。
• docs/configuration.md — 所有设置。
• docs/security.md — 会涉及哪些内容，以及有哪些限制。
• docs/development.md — 构建、测试和发布。

贡献

问题和错误请提交到 issues；欢迎提交 拉取请求。CONTRIBUTING.md 介绍了基本规则和拉取请求流程，且必须通过 make check。

安全

SECURITY.md 说明了如何报告漏洞。请勿为此 公开提交 issue。

行为准则

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

许可证

Apache-2.0 — 详见 LICENSE。