google-drive-files-mcp

google-drive-files-mcp

一个专注于 Google Drive 文件管理（移动、上传、整理）、Google Sheets 编辑（单元格、行、工作表标签、格式）和 Google Docs 精细编辑（替换短语、在锚点处插入、删除范围，同时保留其他所有格式）的 Model Context Protocol 服务（也可独立用作命令行工具）。它提供 23 个细粒度、单一用途的工具——每个工具都对应一项明确操作，写入操作会返回修改前后的内容或精确索引，不会在不知情的情况下更改内容。

开发此服务的原因是：托管的 Google Drive 连接器可以搜索、读取和 复制 文件，但无法 移动 文件（copy 会创建具有新 ID 的副本，而不是移动原文件）；也无法可靠地 上传真实二进制文件（其内嵌内容 API 需要将字节编码为 base64 嵌入内容中，大型或二进制文件无法使用）；也无法原地 编辑电子表格或文档内容。此服务新增了真正的移动功能、从本地路径断点续传上传、创建文件夹、一整套 Google Sheets 编辑功能，以及限定范围的 Google Docs 编辑功能——适用于任何 MCP 客户端（Claude Code、Claude Desktop、Cursor、Cline 等）。

工具

Drive — 文件和文件夹

• drive_search(query, only_folders=False, max_results=20) — 查找文件/文件夹（及其 ID）。
• drive_create_folder(name, parent=None) — 创建文件夹（parent 接受 ID、URL、root 或无歧义的文件夹名称）。
• drive_move(file, dest_folder, keep_existing_parents=False) — 真正移动（从当前文件夹中移除）；keep_existing_parents=True 则只添加到目标文件夹，不从原文件夹移除。
• drive_upload_file(local_path, parent=None, name=None, mime_type=None) — 通过 可续传媒体上传 上传本地文件（任何类型，包括大型二进制文件）。按原样存储（不转换为 Google 格式）。

Google Sheets — 读取、编辑、结构和格式

• sheets_get_info(spreadsheet) — 列出工作表标签及其大小（先调用以获取工作表标签名称）。
• sheets_read(spreadsheet, range_a1, render_option="FORMATTED_VALUE") — 读取范围（也可使用 FORMULA/UNFORMATTED_VALUE）。
• sheets_write(spreadsheet, range_a1, values, value_input_option="USER_ENTERED") — 覆盖范围；返回修改前的内容。USER_ENTERED 会解析数字，并将 =SUM(..) 作为公式处理；RAW 则按字面值写入。
• sheets_append(spreadsheet, range_a1, values, ...) — 在表格后追加行。
• sheets_clear(spreadsheet, range_a1) — 清除值（保留格式）；返回修改前的内容。
• sheets_batch_write(spreadsheet, updates, ...) — 原子性地写入多个范围。
• sheets_add_tab / sheets_rename_tab / sheets_delete_tab — 管理工作表标签（删除操作不可逆）。
• sheets_freeze_panes(spreadsheet, tab, rows=None, cols=None) — 冻结/取消冻结标题行/列（0 = 明确取消冻结；省略 = 不更改）。
• sheets_format(spreadsheet, range_a1, number_format=None, bold=None, background=None, wrap=None) — 设置数字格式 / 粗体 / #RRGGBB 背景色 / 文本换行。
• sheets_set_column_width(spreadsheet, range_a1, pixel_size) — 为整列范围设置列宽（像素）（例如 'A:C'）。
• sheets_set_row_height(spreadsheet, range_a1, pixel_size) — 为整行范围设置行高（像素）（例如 '2:5'）。

Google Docs — 精确的原位编辑

每次 Docs 编辑都限定在指定范围内（documents.batchUpdate），因此只会更改目标内容，其他所有文本段落的原生格式都会逐字节保持不变。

• docs_get_info(document) — 标题和结构（段落数、表格数、结束索引）。
• docs_read(document) — 完整文本，附带每个文本片段的字符索引（表格单元格包含行/列信息）。请先读取，以便定位编辑内容。
• docs_replace_text(document, find, replace, match_case=False) — 替换所有匹配的短语；周围的内容和格式保持不变。
• docs_insert_text(document, text, index=None, after_text=None, before_text=None) — 在指定索引处或锚定短语之后/之前插入文本。
• docs_delete_range(document, start_index, end_index) — 删除一个精确范围。
• docs_append_text(document, text) — 在末尾追加文本。

不会重命名、复制、移至垃圾桶或删除文件（托管版 Drive 连接器已支持复制）；破坏性操作（sheets_clear、sheets_delete_tab、docs_delete_range）各自对应独立工具，让你确切控制它们的执行时机。

权限范围警告（请阅读）

移动已有的任意文件需要完整的 drive 权限范围——可读写和删除你 Drive 中的所有文件。没有更窄的权限范围可以更改文件的父级（drive.file 仅涵盖应用自身创建的文件）。因此，此工具的能力远超只读连接器。请像保护密码一样保护其缓存令牌（以 0600 权限存储），并优先使用隔离的 OAuth 客户端/令牌，而不要与只读工具共用。

安装

pip install google-drive-files-mcp
# or: uv tool install google-drive-files-mcp

一次性设置（约 10 分钟）

1. Google Cloud Console → 创建或选择一个项目。
2. 启用 Drive API（链接）；对于 Sheets 工具，也要启用 Sheets API（链接）；对于 Docs 工具，也要启用 Docs API（链接）。（完整的 drive 权限范围已授权 Sheets 和 Docs API——无需额外授权，只需启用你需要的 API。）
3. OAuth 同意屏幕 → 内部（Workspace；即使使用受限的完整 Drive 权限范围，也无需验证）或 外部 + 将自己添加为测试用户（个人 Gmail）。
4. 凭据 → OAuth 客户端 ID → 桌面应用 → 下载 JSON。
5. google-drive-files-mcp setup --import-credentials ~/Downloads/client_secret_*.json → 在浏览器中授权。

验证：

google-drive-files-mcp status
google-drive-files-mcp search "Reports" --folders

Claude Code

claude mcp add --scope user google-drive-files google-drive-files-mcp -- serve

查找我的“Q2 Report”文档，并将它移至“2026 Reports”文件夹。

Claude Desktop

{
  "mcpServers": {
    "google-drive-files": { "command": "google-drive-files-mcp", "args": ["serve"] }
  }
}

命令行

google-drive-files-mcp search "budget"                 # find a file + its ID
google-drive-files-mcp search "Reports" --folders      # find destination folders
google-drive-files-mcp mkdir "2026 Reports"            # create a folder
google-drive-files-mcp move <file-url-or-id> "2026 Reports"   # move into it (by folder name)
google-drive-files-mcp move <file-url-or-id> root      # move back to My Drive root
google-drive-files-mcp upload ~/Downloads/report.zip --parent "2026 Reports"   # upload a local file

# Google Sheets
google-drive-files-mcp sheet-info  <sheet-url-or-id>                 # list tabs + sizes
google-drive-files-mcp sheet-read  <sheet-url-or-id> "Sheet1!A1:D10" # read a range
google-drive-files-mcp sheet-write <sheet-url-or-id> "Sheet1!B2:B4" '[[100],[200],[300]]'   # set numbers
google-drive-files-mcp sheet-format <sheet-url-or-id> "Sheet1!B2:B4" --number-format '#,##0.00' --bold
google-drive-files-mcp sheet-format <sheet-url-or-id> "Sheet1!A1:B2" --wrap             # wrap text
google-drive-files-mcp sheet-freeze-panes <sheet-url-or-id> Sheet1 --rows 1             # freeze header row
google-drive-files-mcp sheet-set-column-width <sheet-url-or-id> "Sheet1!A:C" 150        # column width (px)
google-drive-files-mcp sheet-set-row-height <sheet-url-or-id> "Sheet1!2:5" 40           # row height (px)

# Google Docs (surgical, in-place)
google-drive-files-mcp doc-read    <doc-url-or-id>                       # text + character indices
google-drive-files-mcp doc-replace <doc-url-or-id> "old phrase" "new phrase"   # preserves all other formatting
google-drive-files-mcp doc-insert  <doc-url-or-id> $'\n\nNew paragraph.' --after "some anchor text"

drive_move 会返回移动前后的父级，因此可审计此次移动：

{ "id": "1Abc…", "name": "Q2 Report", "moved_from": ["0OldFolderId"], "moved_to": "1NewFolderId", "parents_now": ["1NewFolderId"], "web_view_link": "https://docs.google.com/…" }

配置

变量	默认值	说明
GDRIVE_FILES_MCP_CREDENTIALS	~/.config/google-drive-files-mcp/credentials.json	OAuth 客户端密钥
GDRIVE_FILES_MCP_TOKEN	~/.config/google-drive-files-mcp/token.json	缓存的刷新令牌
GDRIVE_FILES_MCP_SCOPES	https://www.googleapis.com/auth/drive	OAuth 权限范围（逗号分隔）

安全提示

• 真正的移动会将文件从当前文件夹中移除。 Drive 项目可以有多个父级；keep_existing_parents=True 会在不移除现有父级的情况下添加新父级。
• 按文件夹名称指定目标时，名称必须唯一。 如果两个文件夹同名，drive_move 会拒绝操作并列出候选项，以便你传入明确的 ID。
• 每次移动都会返回移动前后的父级，供 Agent（或你）验证结果。

故障排除

HttpError 403: Google Drive API has not been used in project … or it is disabled 在拥有 OAuth 客户端的项目中启用 Drive API：console.cloud.google.com/apis/library/drive.googleapis.com → 启用，然后等待约 1 分钟再重试。（这是首次运行时最常见的错误。）

multiple folders named '…'; pass the folder ID/URL instead 有两个或更多文件夹使用了相同名称，因此仅凭名称无法确定是哪一个。运行 google-drive-files-mcp search "<name>" --folders 获取 ID，并传入准确的 ID。

no folder named '…' found 请先创建文件夹（google-drive-files-mcp mkdir "<name>"），或传入文件夹 ID、URL 或 root。

移动时出现 HttpError 403: insufficientFilePermissions 要么是令牌没有完整的 drive 范围——请运行 google-drive-files-mcp setup --reauth 重新授权；要么是你没有该文件或目标位置的编辑权限（除非文件所有者授予你编辑权限，否则你无法移动他人拥有的文件）。

Claude Desktop / cron 提示 No valid Google token 首次授权需要使用浏览器。在终端中运行一次 google-drive-files-mcp setup；之后的无头运行会复用缓存的令牌并自动刷新。

移动操作意外地将文件从共享文件夹中“移除” 真正的移动会将项目从当前父级文件夹中移除。如果你想让文件也保留在原位置，请使用 keep_existing_parents=true（CLI 参数 --keep）。

在其他客户端中使用（Cursor、Cline、Continue 等）

任何 stdio MCP 客户端都可以使用——请参阅 docs/other-clients.md。

身份验证——使用你自己的 Google OAuth 客户端

不需要 API 密钥，也不包含随附的密钥。服务会通过你创建的 OAuth 客户端连接到你的 Google 账号，并在本地缓存刷新令牌。作者无法访问你的数据。

• 为什么要使用自己的客户端？ Google 的受限范围（此处为完整的 drive 范围）无法在共享应用中再分发，而未经验证的共享应用最多只能支持 100 位用户。“使用自己的 OAuth 客户端”是个人数据 MCP 服务的标准做法。
• 你需要准备： 一个免费的 Google Cloud 项目、已启用的 Drive API、OAuth 同意屏幕和一个 Desktop OAuth 客户端。完整指南 → docs/setup-google-oauth.md。
• 令牌存储位置： ~/.config/google-drive-files-mcp/token.json（权限模式 0600）。删除该文件可在本地撤销令牌；前往 myaccount.google.com/permissions 可完全撤销。
• 没有托管/SaaS 选项——所有操作都在本地运行；你的 Drive 数据绝不会经过第三方服务。

更多指南

• docs/setup-google-oauth.md — 完整的 OAuth 设置指南（完整的 drive 范围）及常见错误
• docs/claude-code.md · docs/claude-desktop.md · docs/other-clients.md
• examples/ — 例如，将文档归档到 YYYY-MM 文件夹中

相关工具

这是一个专注于本地 Google Workspace 数据的 MCP 服务小系列的一部分，可访问托管连接器无法提供的数据：

• gmail-attachments-mcp — 将 Gmail 附件内容下载到磁盘
• google-drive-comments-mcp — 读取 Docs/Sheets/Slides 中的评论串
• google-drive-files-mcp — 移动/整理 Drive 文件 (本仓库)

这些工具可以共用一个 OAuth 登录，也可以彼此隔离——请参阅各仓库中的设置说明。

许可证

MIT。请参阅 LICENSE。