google-drive-mcp

一个本地 MCP 服务器，为 Claude Code 提供全范围 Google Drive 访问权限—— 搜索、读取、上传、重命名、移动和更改共享权限——包括对 Drive 中已存在的文件（不仅仅是此应用创建的文件）进行操作。

它特意请求了广泛的 https://www.googleapis.com/auth/drive 范围， 因为其构建的任务（重命名、移动和更改现有课程文件的共享权限） 无法通过更窄的 drive.file 范围完成。

一次性设置

你只需执行一次。之后，每个 Claude Code 会话都可以使用 google-drive 工具。

步骤 1 — 创建 Google Cloud 项目（如果已有可跳过）

1. 访问 https://console.cloud.google.com/。

2. 顶部栏 → 项目下拉菜单 → 新建项目。

3. 命名为类似 app-integrations → 创建。等待几秒钟，然后 确保顶部栏中已选中该项目。

步骤 2 — 启用 Google Drive API

1. 访问 https://console.cloud.google.com/apis/library/drive.googleapis.com。

2. 确认已选中你的项目 → 点击启用。

步骤 3 — 配置 OAuth 同意屏幕

1. 访问 https://console.cloud.google.com/auth/overview（API 和服务 → OAuth 同意屏幕）。

2. 如果提示，选择用户类型：外部 → 创建。 （外部对于个人 Google 帐户没问题；你只需成为“测试用户”。）

3. 填写必填字段：

   • 应用名称：google-drive-mcp（任何名称都可以）

   • 用户支持邮箱：你的邮箱

   • 开发者联系邮箱：你的邮箱

   • 保存并继续。

4. 范围页面：你无需在此处添加范围——服务器会在授权时请求它们。保存并继续。

5. 测试用户页面：点击**+ 添加用户并添加你自己的 Google 邮箱** （你自己的 Google 帐户）。当应用处于“测试”状态时，这是必需的。保存并继续。

你无需发布应用或通过 Google 验证。测试状态的应用对你列出的测试用户 可以无限期使用；测试应用的刷新令牌在 7 天不使用后可能会过期——如果 Drive 工具 开始出现授权错误，只需重新运行 npm run auth（步骤 6）。

步骤 4 — 创建 OAuth 客户端（桌面应用）

1. 访问 https://console.cloud.google.com/auth/clients（API 和服务 → 凭据）。

2. + 创建凭据 → OAuth 客户端 ID。

3. 应用类型：桌面应用。命名为 desktop-mcp → 创建。

4. 在对话框中，点击下载 JSON。

步骤 5 — 将客户端文件放在服务器期望的位置

将下载的 JSON 保存到以下确切路径/名称：

~/.config/google-drive-mcp/gcp-oauth.keys.json

例如，如果它下载到 ~/Downloads/client_secret_XXXX.json：

mkdir -p ~/.config/google-drive-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-drive-mcp/gcp-oauth.keys.json

步骤 6 — 授权（一次）

cd ~/mcp-servers/google-drive-mcp
npm run auth

这会打印一个 URL 并打开你的浏览器。使用你想要管理其 Drive 的 Google 帐户登录。 你会看到“Google 尚未验证此应用”的警告（这是预期的，因为应用处于测试状态）→ 高级 → 前往 google-drive-mcp（不安全） → 继续 → 允许 Drive 权限。

成功后，它会写入 ~/.config/google-drive-mcp/.gdrive-credentials.json （你的刷新令牌——请保密；它已经设置了 chmod 600）。

步骤 7 — 使用它

服务器已在 ~/.claude.json 中以名称 google-drive 注册。启动一个新的 Claude Code 会话，gdrive_* 工具将可用。（MCP 服务器在会话启动时加载， 因此在注册之前启动的会话不会看到它们。）

快速手动冒烟测试（可选）：

cd ~/mcp-servers/google-drive-mcp && npm start
# prints "google-drive-mcp: connected over stdio", then waits. Ctrl-C to quit.

工具

删除内容

gdrive_trash 是首选。它是可逆的，Drive 将已删除项目保留 30 天， 并且 gdrive_untrash 可以将它们放回原处。

gdrive_delete 是永久且不可恢复的——不会进入回收站。它要求 confirmName 与项目当前名称完全匹配，这强制在销毁任何内容之前进行元数据读取， 因此过时或输入错误的文件 ID 会大声失败，而不是删除错误的内容。删除文件夹会删除其内部所有内容。

注册

在两个配置中都已注册——它们是独立读取的，因此在一个中注册不会使服务器在另一个中可用：

• ~/.claude.json（Claude Code）

• ~/Library/Application Support/Claude/claude_desktop_config.json（桌面版 / Cowork）

每个中的条目相同：

"google-drive": {
  "command": "/opt/homebrew/bin/node",
  "args": ["/ABSOLUTE/PATH/TO/mcp-servers/google-drive-mcp/index.js"]
}

需要 node 的绝对路径，这不是风格选择。 从 Finder 或登录时启动的应用 继承最小的 launchd PATH（/usr/bin:/bin:/usr/sbin:/sbin）， 其中 Homebrew 的 /opt/homebrew/bin/node 完全不可见。裸的 "node" 在每次从终端测试时都有效， 但每天早上都会失败。~/mcp-servers/trello-mcp/doctor.py 会检查两个配置中的每个服务器是否存在此问题。

如果你稍后安装 claude CLI，等效命令是：

claude mcp add --scope user google-drive -- /opt/homebrew/bin/node ~/mcp-servers/google-drive-mcp/index.js

文件

• index.js — MCP 服务器（工具定义）

• auth.js — 一次性 npm run auth 回环 OAuth 流程

• lib-auth.js — 共享的 OAuth/配置辅助函数

• ~/.config/google-drive-mcp/gcp-oauth.keys.json — 你提供（步骤 5）

• ~/.config/google-drive-mcp/.gdrive-credentials.json — 由 npm run auth 创建

用于简历/作品集

保留在这里，以便未来的简历会话有真实的版本，而不是重新构建。

为什么在已有 Drive 连接器的情况下还要创建这个。 它扩展了内置连接器，而不是替换它。 差距在于批量工作：当命名约定在项目中途更改时，重命名一百个文件手动操作很繁琐， 通过脚本则很简单，并且值得永久解决，而不是一次性解决。这就是动机案例。

我实际做了什么： 设定目标和约束——一个免费的解决方案， 在未来的每个项目上节省相同的时间，而不是一个针对单个文件夹的一次性脚本。

已知的操作注意事项： OAuth 应用的发布状态决定了刷新令牌的有效期。 在“测试”状态下，它们大约每周过期（invalid_grant）； 发布应用会移除该限制，适用于共享该 Cloud 项目的所有集成。

作品集长度的要点： 请参阅 ~/mcp-servers/trello-mcp/README.md 中的共享版本—— 这三个最好一起描述。

完整案例研究：https://zeno-blade-creator.github.io/projects/personal-integrations.html