用途
mcp-google-drive 是一个 MCP（Model Context Protocol）服务器，用于连接 Google Drive API，让 AI 应用以自然语言方式操作 Google Drive。它面向 Claude、Cursor、Codex 及其他 AI 客户端，可查看 My Drive 和共享云端硬盘。
主要能力
服务器共提供 21 个工具，涵盖以下方面：
- 搜索与元数据：查找文件、查看文件位置与所有者等信息。
- 文件夹与移动：创建文件夹、移动文件。
- 上传与下载：上传内容、下载文件。
- 导出：将 Google Docs、Sheets、Slides 导出为其他格式（如 Markdown）。
- 回收站：将文件移入可恢复的回收站，以及恢复误删文件。
- 共享与评论：共享文件或文件夹、添加评论、列出并解决评论、撤销访问权限。
设计上的几个特点：
- 回收站优先：“删除”默认指可恢复的回收站，永久删除是单独的工具，不会被误选。
- 文档保持完整：Docs、Sheets、Slides 以整体文件形式移动、复制、导出和转换，服务器不会编辑文档内部的文本或单元格。
- 作用域可选：drive.readonly 覆盖所有读取操作；drive.file 仅限应用创建的文件；完整工具集需要 drive 作用域。
- 写入不重放：网络和 5xx 错误后的重试仅适用于读取，复制、上传或新建文件夹不会在不确定失败后被重复执行。
使用方式
需要 Node.js 20+ 和 Google 账号。安装时不需要凭据，服务器可从对话中连接。
基本流程：
- 将服务器添加到 AI 应用。
- 说“connect Google Drive”，助手会引导创建 OAuth 客户端并批准访问，无需编辑配置文件。
- 提出只读问题开始使用，例如：查找我 Drive 中的项目路线图文档，导出为 Markdown 并总结。
在桌面应用中：打开 Settings → MCP servers，选择 Add server，选择 STDIO，输入命令 npx -y @a1-x-tech/mcp-google-drive@latest 以及环境变量 GOOGLE_DRIVE_CLIENT_ID、GOOGLE_DRIVE_CLIENT_SECRET 和 GOOGLE_DRIVE_REFRESH_TOKEN。保存后重启。
在 IDE 扩展中：打开齿轮菜单 → MCP servers，选择 Add server，选择 STDIO，输入相同命令和环境变量。保存后重启扩展。
命令行方式可参考 Codex MCP 文档和 Claude Code MCP 文档。
Claude Desktop 当前官方路径是 Settings → Extensions。自定义桌面扩展可打开 Advanced settings → Extension Developer → Install Extension…，选择 .mcpb 文件并按提示操作。该仓库目前发布的是 npm stdio 包，不包含 .mcpb 包。对于仍支持本地配置的 Claude Desktop 版本，可使用 JSON stdio 配置作为回退，保存到 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 的 %APPDATA%\Claude\claude_desktop_config.json。
Cursor：在 macOS/Linux 的 ~/.cursor/mcp.json 或 Windows 的 %USERPROFILE%\.cursor\mcp.json 中添加配置。
VS Code：运行 MCP: Open User Configuration 并添加配置，用 MCP: List Servers 检查。
从对话连接（推荐）
说“connect Google Drive”后，助手会运行以下流程：
- setup_instructions 打印检查清单：创建或选择 Google Cloud 项目、启用 Google Drive API、配置同意屏幕并创建 Desktop app OAuth 客户端。
- 下载该客户端的 JSON（“Download JSON”），将路径提供给助手——set_client 会以仅所有者权限存储它。密钥不会经过对话。
- start_login 返回 Google 同意链接。在本机打开并批准；代码通过 127.0.0.1 上的一次性监听器（PKCE）返回，不经过聊天。
- finish_login 交换代码并将令牌保存到
~/.config/mcp-google-drive/credentials.json（权限 0600），并通过真实的 Google Drive API 调用验证。
令牌在每次调用时重新读取，因此连接立即生效，无需重启 AI 应用。auth_status 显示连接状态，logout 撤销并删除凭据。
环境变量（CI、无人值守安装）
- 创建或选择 Google Cloud 项目并启用 Google Drive API。
- 配置 OAuth 同意屏幕并创建 Desktop app OAuth 客户端。
- 授权服务器应操作的 Google 账号。启用“Use your own OAuth credentials”时，OAuth 2.0 Playground 可获取刷新令牌。
作用域选择：
https://www.googleapis.com/auth/drive.readonly：只读工具，包括搜索、元数据、下载、导出和共享云端硬盘列表。https://www.googleapis.com/auth/drive.file：仅限此应用创建或打开的文件，适用于应用自有文件的上传和整理流程。https://www.googleapis.com/auth/drive：完整工具集，包括对任意文件的共享、回收站、删除和评论。
服务器使用刷新令牌签发时的作用域；超出该作用域的调用会以 insufficientPermissions 错误失败。
测试模式的 OAuth 刷新令牌可能在七天后过期。需要长期访问时，请发布 OAuth 应用，或在 Workspace 域中使用 Internal 应用。请将客户端密钥和刷新令牌视为密码。
所有变量都是可选的——不设置任何变量时，服务器从对话连接。需提供 OAuth 三件套或访问令牌。没有任何凭据时，服务器仍会启动并完成 MCP 握手；首次工具调用会回复需要设置的具体变量，而不是死掉。
适用场景
- 查找并读取文件：查找上季度预算表并显示位置和所有者；将项目简报导出为 Markdown 并总结未决问题；将已签署的合同 PDF 下载到报告文件夹。
- 整理和传输内容：创建“2026 Reports”文件夹并移动月度报告；上传会议记录并转换为 Google Doc；复制提案模板并为新客户重命名副本。
- 共享与讨论：将文件夹以评论者身份共享给队友并添加备注；列出设计文档的未解决评论并解决已处理的；撤销外部承包商对存档的访问权限。
- 谨慎清理：将过时草稿移入回收站，并恢复误删的一个；确认后永久删除测试上传文件夹；在清除前显示回收站内容。
限制
- Drive 中所有内容（包括文件夹和共享云端硬盘项目）都是带 id 的文件。名称不唯一，工具按 id 操作，重名合法，创建前最好先搜索。
- “删除”指回收站：可恢复，Google 约 30 天后自动清除。永久删除绕过回收站，会连同文件夹子树一起删除，位于单独的工具中。
- Google Docs、Sheets 和 Slides 以整体单位移动、复制、共享、导出和转换。服务器没有编辑 Doc 内文本或 Sheet 内单元格的工具。
- 内置上传限制为 5 MB（更大文件通过 raw_request 使用可恢复会话），导出限制为 10 MB（依据 Drive API）。通过 API 创建的评论无法锚定到 Doc 内的特定段落。
- AI 客户端控制确认提示。服务器标记读取、写入和破坏性工具，以便客户端区分检查和实际更改。
- Google Drive 需要 OAuth 2.0，API 密钥不够。
- 请求发往 Google Drive。本地服务器刷新 Google OAuth 令牌并调用 Drive API。其匿名遥测包含安装 ID、包版本、AI 客户端和平台版本以及工具名称——绝不包含 OAuth 令牌、文件内容、工具参数或提示。设置 ASKADS_TELEMETRY=0 可退出。
- Google 施加配额和大小上限。遇到 429 时服务器使用退避；读取也会在网络和 5xx 错误后重试，而写入在不确定失败后不会重放。
- 本地文件处理谨慎。下载仅保存到绝对路径，除非要求否则拒绝覆盖现有文件；内联返回的文本内容上限为 100 KB。
- 没有后台轮询。服务器仅在调用时运行；请求之间不会监视 Drive。如果 AI 应用支持计划任务，可以定期检查更改。
