Google Drive MCP

Google Drive MCP 服务

通过一个可自托管的服务，将 MCP 客户端连接到 Google Drive、Docs、Sheets、Slides 和 Calendar。搜索和整理文件，创建和编辑 Workspace 内容，管理共享，并自动执行多步骤工作流，同时掌控每次调用所使用的 Google 身份和凭据。

为什么选择此服务

• 以 Drive 为核心的工作流： 130 个工具涵盖文件管理、共享云端硬盘、权限、修订版本、丰富的 Docs 编辑、Sheets 格式设置、Slides 创作和 Calendar 活动。
• 本地或托管： 个人桌面客户端可使用 stdio，托管集成可使用 Streamable HTTP，共享服务可使用受 OAuth 保护的团队模式。
• 身份控制： 本地 OAuth 支持多个 Google 账号和按工具选择账号；也支持服务账号和外部管理的 OAuth 令牌。
• 便于 Agent 使用的访问方式： 工具提供针对性操作，而可选的 gdrive:/// 资源接口支持直接读取和发现。
• 开源且可自托管： 凭据和令牌保留在你所运营的环境中。

本项目专注于深入支持 Drive 和编辑器工作流，而非试图开放所有 Google Workspace API。

客户端兼容性

兼容性取决于客户端支持的传输方式和身份验证流程。

客户端类型	传输方式	推荐模式
Claude Desktop	stdio	本地 OAuth
其他本地 MCP 客户端，包括 Gemini CLI	stdio	本地 OAuth
claude.ai 自定义连接器	Streamable HTTP	团队模式
其他远程 MCP 客户端	Streamable HTTP	访问控制下的单一身份，或使用 OAuth 2.1 的团队模式

请参阅客户端配置，了解配置示例和传输要求。

快速开始

1. 创建 Google OAuth 凭据

在 Google Cloud 项目中：

1. 启用 Drive、Docs、Sheets、Slides 和 Calendar API。
2. 配置 OAuth 同意屏幕；如果应用处于测试阶段，请将你的 Google 账号添加为测试用户。
3. 创建应用类型为 桌面应用 的 OAuth 客户端。
4. 下载 JSON 文件并保存为：

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

设置指南提供了完整的 Google Cloud 操作说明以及其他凭据存放位置。

2. 进行身份验证

npx -y @piotr-agier/google-drive-mcp auth

在浏览器中完成 Google 同意流程。令牌默认保存在 ~/.config/google-drive-mcp/tokens.json。

3. 将服务添加到 MCP 客户端

对于使用通用 mcpServers 配置格式的客户端：

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "@piotr-agier/google-drive-mcp"]
    }
  }
}

保存配置后重启客户端。Claude Desktop 路径和 HTTP 示例见客户端配置。

4. 首次调用工具

向客户端提问：

Run authGetStatus and tell me which Google account is active.

然后尝试发起只读的 Drive 请求：

Search my Google Drive for files modified in the last seven days.

如果身份不正确或搜索没有返回文件，请查看故障排除指南。

你可以做什么

整理 Drive

Find PDF files in /Reports, create an Archive folder there, and move files older
than one year into it.

生成报告

Create a Google Sheet for monthly results, summarize it in a Google Doc, and
create a short Google Slides presentation from the summary.

编辑文档

Find the "Project Plan" document, replace the old launch date, format the new
date in bold, and add a comment describing the change.

准备会议

Create a Calendar event with a Google Meet link and attach the project brief
from Drive.

文档

README 中原有的所有章节现在都收录在以下指南中。

指南	内容
设置	要求、Google Cloud API、OAuth 凭据和安装
客户端配置	支持的传输方式和客户端配置
身份验证	本地 OAuth、多账户、服务账户、外部令牌和作用域
配置	CLI 标志、环境变量、默认值和优先级
部署	Docker、Streamable HTTP、团队模式和反向代理安全
工具参考	所有 Drive、Docs、Sheets、Slides、Calendar 和账户工具
故障排除	身份验证、API、身份、Docker 和速率限制问题
开发	仓库结构、构建命令、测试和贡献

安全

• 切勿提交 OAuth 凭据、服务账户密钥、访问令牌、刷新令牌或 tokens.json。
• 使用能够支持所需工具的最小 OAuth 作用域。
• 除非服务受到 TLS 和访问控制保护，否则请将默认 HTTP 绑定地址保持为 127.0.0.1。
• 对于共享部署，请使用团队模式，确保每个请求都以发起者的身份进行身份验证。
• 将 team-store.json 视为机密，因为其中包含成员的 Google 刷新令牌。

有关完整的安全和身份模型，请参阅身份验证和部署。

开发与支持

请参阅开发指南，了解如何构建和测试项目。

• 在 GitHub Issues 中报告缺陷和请求功能。
• 在更新日志中查看已发布的更改。
• 欢迎通过拉取请求贡献代码。

许可证

MIT

致谢

• 基于 Model Context Protocol 构建。
• 使用 Google APIs Node.js Client。