title: "Google Drive MCP Server" date: 2026-08-19 tags:

• проект/workspace

• подпроект/tools

• тип/guide

• область/tech

• дата/2026-08-19

Google Drive MCP Server

本地 MCP 服务器，适用于 Cursor、Claude Code 和 Claude Desktop。通过它，代理可以搜索和读取 Google Drive 上的文件，创建和编辑 Google Docs 和 Google Sheets。

Google Docs 读取时转换为 Markdown，表格转换为 CSV，演示文稿转换为文本。Docs 可以精确编辑：插入、替换、样式、标题、列表、重命名、复制。Sheets 可以编辑值、格式、工作表、行和列。既支持个人 Drive，也支持 Shared drives。

仓库：https://github.com/Stillfrozen/gdrive-mcp
基于 wagnerlabs/gdrive-mcp。

OAuth 密钥只保存在您的本地磁盘上，不会进入 git。

在 Google Cloud 中逐步安装（项目、API、Desktop OAuth、test users）： docs/INSTALL.ru.md

快速开始

需要 Node.js 18+（最好 20）和一个 Google 账号，您将使用该账号的 Drive。

git clone https://github.com/Stillfrozen/gdrive-mcp.git
cd gdrive-mcp
./scripts/install.sh

脚本会安装依赖、构建项目，并引导您完成 Google Cloud 设置：项目、API、同意屏幕、Desktop 客户端、浏览器登录。最后会打印出适用于 MCP 客户端的现成配置片段。

查看步骤而不做任何更改：

./scripts/install.sh --dry-run

如果您想自己在 Console 中操作——所有屏幕的详细说明见 docs/INSTALL.ru.md。

Cursor

在 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）中——仅使用绝对路径：

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"],
      "env": {
        "GDRIVE_OAUTH_PATH": "/absolute/path/to/gdrive-mcp/credentials/gcp-oauth.keys.json",
        "GDRIVE_CREDENTIALS_PATH": "/absolute/path/to/gdrive-mcp/credentials/.gdrive-server-credentials.json"
      }
    }
  }
}

如果 JSON 文件位于仓库的 credentials/ 目录中，则 env 块不是必需的。如果文件中已有其他服务器，请将 "gdrive" 添加到 mcpServers 中，不要覆盖其他内容。

然后 Cursor → Settings → MCP → Reload。gdrive 指示器应变为绿色。

Claude Code CLI

claude mcp add --scope user gdrive -- node /absolute/path/to/gdrive-mcp/dist/index.js

--scope user 将服务器全局安装。移除：claude mcp remove gdrive。

Claude Desktop

在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"]
    }
  }
}

Related MCP server: Google Drive MCP Server

工具

读取

写入：Sheets

写入：Docs

如何将值写入单元格

gdrive_update_sheet 和 gdrive_append_sheet 的参数 value_input_option：

• USER_ENTERED（默认）— 如同在 Sheets UI 中输入。公式 =SUM(A1:A10) 会执行，数字和日期会格式化。

• RAW — 原样输入。字符串 =SUM(A1:A10) 将保持为文本。

如何读取文件

gdrive_read_file 会自动导出 Workspace 文档：

整个表格（工作表、结构、写入）请通过 gdrive_get_spreadsheet_info 和 Sheets 写入工具获取，不要使用 gdrive_read_file。

对于 Doc 的段落、标题、列表和锚点编辑，请使用 gdrive_get_document_info。响应中包含原始 text 和不带段落尾部换行符的 displayText；displayText 通常作为锚点更安全。Markdown 最快由 gdrive_read_file 提供。

安全模型

多层安全：MCP 注释、“先读后写”、Docs 的修订和锚点、Sheets 的当前值核对。

1. 工具注释

每个工具都声明了 MCP annotations。客户端可以在破坏性操作前请求确认。请参阅上表中的 Destructive / Idempotent 列。

2. 先读取，后写入

服务器会记住代理在当前会话中已打开过的表格和 Docs。

表格在以下操作后被视为已读取：

• gdrive_read_file（单元格作为 CSV）

• gdrive_get_spreadsheet_info（结构和工作表）

• gdrive_create_sheet（代理刚刚创建了文件）

Doc 在以下操作后被视为已读取：

• gdrive_read_file（Markdown + 修订，如果 Google 提供了）

• gdrive_get_document_info（工作表或结构化文本）

• gdrive_create_doc

任何未经过此步骤的写入都会被拒绝：

You must read this spreadsheet before writing to it…

You must read this document before writing to it…

这样代理就不太可能误操作错误的文件。列表在进程重启时重置（每个 MCP 会话重新开始）。

gdrive_get_file 不在此列：它只返回 Drive 元数据，不返回内容。

3. 带修订的 Docs 写入

编辑绑定到代理最后读取的修订：

• conflict_mode: "strict"（默认）— Docs requiredRevisionId。如果文档已被修改，写入将失败。

• conflict_mode: "merge" — Docs targetRevisionId。Google 会尽可能将您的更改与外部修改合并。

结构化内容缓存存在于会话中，在 gdrive_get_document_info include_content=true 之后。锚点工具（gdrive_insert_doc_text、gdrive_replace_doc_text、gdrive_update_doc_paragraph_style、gdrive_update_doc_list）在修订未变时使用该缓存。否则，服务器会重新获取快照。

对于精确文本替换，可以传递 expected_text：在发送前，服务器会验证该范围是否包含该字符串。

对于锚点 gdrive_delete_doc_text 和 gdrive_replace_doc_text，如果匹配到工作表末尾，服务器会自动截断段落末尾的换行符。Docs API 无法删除带有段尾换行符的范围。显式的 start_index / end_index 不会这样做：必须自行排除尾部换行符。

4. Sheets 的前提条件

gdrive_update_sheet 有一个可选的 expected_current_values — 与 values 形状相同的二维数组。服务器会读取单元格并比较。如果不匹配，则拒绝写入，并在错误中返回实际内容。

• 精确编辑（单个单元格、公式）— 请传递 expected_current_values。

• 批量操作（数千行）— 不要传递，否则请求数会翻倍并触发配额限制。

include_previous_values: true 将返回旧值以供审计。如果指定了 expected_current_values，则始终返回旧值。

回滚

Docs 和 Sheets 的编辑在 Google Workspace 的版本历史中可见。可以在那里回滚。

没有工具会从 Drive 中完全删除文件。 破坏性操作仅发生在 Doc 内部和表格内部。删除文件只能通过 Drive UI 进行。

配置

密钥路径可以通过环境变量覆盖：

更新

在 git pull 之后运行 upgrade。它会重新构建项目，如果 setup-manifest.json 中出现了新的 API 或 scope，则会要求重新进行 auth：

cd /path/to/gdrive-mcp
git pull
./scripts/upgrade.sh

如果清单未更改，脚本只会重新构建并告知您已就绪。Cursor 将在 Reload MCP 后拾取 dist/。无需重新注册服务器。

关于 scope： 服务器请求完整的 drive，而不是更窄的 drive.file。这比 Google 的最低建议更宽，但否则无法读取任意可访问的文件并写入已存在的 Docs（rename、duplicate、编辑）。documents scope 用于结构化读取和 batchUpdate。

对于处于 Testing 状态的外部应用，refresh token 的有效期为 7 天。之后会返回 invalid_grant，需要再次运行 npm run auth。详细信息及选项（Internal / Publish）见 docs/INSTALL.ru.md。

限制

• gdrive_create_sheet 将表格放在 Drive 根目录。无法选择文件夹。

• gdrive_read_file 对于 Sheets 仅返回第一个工作表的 CSV。其他工作表请使用 gdrive_get_spreadsheet_info。

• gdrive_read_file 对于 Docs 始终返回 Markdown。工作表、段落边界、列表、锚点 — 请使用 gdrive_get_document_info。

• 在更改 Doc 的格式和结构之前，请先读取 gdrive_get_document_info include_content=true。

• gdrive_replace_all_doc_text 默认仅处理第一个工作表。要处理所有工作表，必须显式指定 all_tabs: true。

开发

npm install
npm run dev          # tsx, без сборки
npm run build
npm test
npm run test:live    # живой Google Doc, нужны сохранённые credentials
npm run test:watch

npm run test:live 创建一个临时 Doc，通过与 MCP 相同的流插入文本，通过 gdrive_get_document_info 检查，最后将文件放入回收站。

许可证

MIT