Gdrive MCP

gdrive mcp

提供对Google Drive文档访问的模型上下文协议（MCP）服务器。

特性

• 搜索驱动：在整个Google云端硬盘中搜索文件和文档
• get_doc_contents：通过URL或文档ID检索Google文档的全文内容
• list_doc_注释：列出Google文档上的所有评论线程及其详细信息
• create_doc_comment：在Google文档上创建未编排的评论
• 回复：回复现有评论帖子
• insert_doc_note：插入自动编号的样式注释块(📝 注1：，📝 注2：等）纳入文件内容
• update_doc_note：按编号更新现有说明的文本
• remove_doc_note：按编号从文档中删除注释

安装

无需安装！使用 bunx 直接运行或从源代码克隆。

选项1：与拇囊炎一起使用（推荐）

无需安装- bunx 将自动下载并缓存该包。

选项2：从源克隆

git clone https://github.com/benjamine/gdrive-mcp.git
cd gdrive-mcp
bun install

快速开始

2.创建Google OAuth2凭据

您需要从Google Cloud Console创建自己的OAuth2凭据。

📖 请参阅详细说明: docs/CREATE_ONATH_CREDENTIALS.md

快速版本：

1. 首选 Google 云控制台
2. 创建项目并启用Google Drive API+Google Docs API
3. 创建OAuth 2.0桌面凭据
4. 复制您的客户端ID和客户端密码

3.运行OAuth安装程序

安装脚本将打开浏览器并处理OAuth2流：

使用bunx（推荐）：

bunx --bun -p gdrive-mcp gdrive-mcp-auth YOUR_CLIENT_ID YOUR_CLIENT_SECRET

如果从源克隆：

bun run src/setup-auth.ts YOUR_CLIENT_ID YOUR_CLIENT_SECRET

这将：

1. ✅ 打开浏览器进行谷歌授权
2. ✅ 自动处理OAuth2回调
3. ✅ 将凭据安全地存储在系统密钥链中
4. ✅ 显示配置已准备好复制

输出示例：

✨ Setup Complete!

✅ Credentials stored securely in your system keychain
   (macOS Keychain / Linux libsecret / Windows Credential Manager)

Add this to your Claude Desktop config:
{
  "mcpServers": {
    "gdrive": {
      "command": "bunx",
      "args": ["--bun", "gdrive-mcp"]
    }
  }
}

💡 No need to store sensitive credentials in config files!

4.配置MCP客户端

将服务器添加到MCP客户端配置中。

注： 凭据安全地存储在您的系统密钥链（macOS密钥链、Linux libsecret或Windows凭据管理器）中，无需将其添加到配置文件中！

开源代码

添加到您的 opencode.jsonc:

使用bunx（推荐）：

{
  "mcp": {
    "gdrive": {
      "type": "local",
      "command": ["bunx", "--bun", "gdrive-mcp"]
    }
  }
}

如果从源克隆：

{
  "mcp": {
    "gdrive": {
      "type": "local",
      "command": ["bun", "run", "/absolute/path/to/gdrive-mcp/src/index.ts"]
    }
  }
}

克劳德桌面

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

使用bunx（推荐）：

{
  "mcpServers": {
    "gdrive": {
      "command": "bunx",
      "args": ["--bun", "gdrive-mcp"]
    }
  }
}

如果从源克隆：

{
  "mcpServers": {
    "gdrive": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gdrive-mcp/src/index.ts"]
    }
  }
}

用法

可用工具

搜索驱动

使用文本查询在整个Google Drive中搜索文件和文档。

参数：

• query （string）：搜索查询文本。支持Google Drive搜索语法：

- 简单文本： "quarterly report" -在文件名和内容中搜索 - 按名称： name:report -仅搜索文件名 - 按类型： type:document -按文件类型筛选 - 组合： type:spreadsheet budget -组合过滤器

• max_results （number，可选）：返回的最大结果数（默认值：10，最大值：100）

退货：

• 每个匹配文件的文件名、类型、ID、修改日期、所有者、大小和查看链接

示例：

{
  "query": "quarterly report",
  "max_results": 20
}

{
  "query": "type:document name:meeting",
  "max_results": 10
}

get_doc_contents

检索Google文档的全文内容。

参数：

• doc_id_or_url （string）：完整的谷歌文档URL或仅文档ID

示例：

• 网址： https://docs.google.com/document/d/1a2b3c4d5e6f7g8h9i0j/edit
• 文档ID: 1a2b3c4d5e6f7g8h9i0j

list_doc_注释

列出Google文档上的所有评论线程，包括引用文本、回复和状态。

参数：

• doc_id_or_url （string）：谷歌文档URL或文档ID

create_doc_comment

在Google文档上创建未编排的评论（显示在“所有评论”视图中）。

参数：

• doc_id_or_url （string）：谷歌文档URL或文档ID
• comment （string）：要添加的注释文本

注： 由于Google Drive API的限制，评论无法锚定到特定的文本选择。

回复

对Google文档上现有评论线程的回复。

参数：

• doc_id_or_url （string）：谷歌文档URL或文档ID
• comment_id （string）：要回复的评论的ID
• reply （string）：回复文本

insert_doc_note

将自动编号的样式注释块直接插入到文档内容中。注释会自动按顺序编号(📝 注1：，📝 注2：等）。这是API无法创建锚定评论或建议的解决方法。该注释显示为一个视觉上独特的块，具有：

• 自动递增钞票编号
• 彩色背景（浅黄色/奶油色）
• 缩进和间距
• 醒目的彩色标题
• 正常文本大小，便于阅读

参数：

• doc_id_or_url （string）：谷歌文档URL或文档ID
• search_text （string）：要搜索的确切文本；将在包含此文本的段落后插入注释
• note （string）：注释文本（“📝 注#：“前缀是自动添加的）

例子：

{
  "doc_id_or_url": "https://docs.google.com/document/d/...",
  "search_text": "Email Template",
  "note": "Consider using a more modern email format with clear sections and bullet points."
}

这将插入一个黄色背景的样式块，如下所示：

📝 NOTE 1: Consider using a more modern email 
format with clear sections and bullet points.

（带缩进、黄色背景和间距）

update_doc_note

按编号更新现有注释的文本。注释编号和格式保持不变。

参数：

• doc_id_or_url （string）：谷歌文档URL或文档ID
• note_number （number）：要更新的钞票编号（例如，1代表📝 注1：）
• new_text （string）：新的注释文本（没有'📝 注#：前缀）

remove_doc_note

按编号从文档中删除注释。这将完全删除包括所有格式在内的注释块。

参数：

• doc_id_or_url （string）：谷歌文档URL或文档ID
• note_number （number）：要删除的钞票编号（例如，1代表📝 注1：）

测试服务器

运行OAuth设置后，您可以直接测试服务器：

bunx --bun gdrive-mcp

服务器将自动从您的系统密钥链加载凭据。

故障排除

“访问被阻止：授权错误-找不到OAuth客户端”

此错误表示您使用的是占位符/无效凭据。您需要：

1. 创建自己的OAuth2凭据（请参阅 docs/CREATE_ONATH_CREDENTIALS.md)
2. 使用您的凭据运行安装脚本

“未收到刷新令牌”

如果您之前已授权该应用程序：

1. 首选https://myaccount.google.com/permissions
2. 删除“gdrive mcp”应用程序
3. 再次运行安装程序

端口48127已在使用中

更改 REDIRECT_PORT 在 src/setup-auth.ts 到另一个港口。

发展

装订和格式化

此项目使用Biome进行修剪和格式化：

# Check code
bun run check

# Format code
bun run format

# Lint and fix
bun run lint

运作原理

此MCP服务器使用OAuth2和基于浏览器的同意流，类似于流行的工具，如 rclone:

1. 设置阶段：运行 src/setup-auth.ts 这将启动本地回调服务器并打开您的浏览器
2. 授权：您在Google的OAuth同意屏幕中批准该应用程序
3. 代币兑换：身份验证码被交换为刷新令牌
4. 安全存储：凭据存储在您的系统密钥链中，使用 Bun.secrets
5. 运行时：MCP服务器从密钥链加载凭据，并使用刷新令牌获取临时访问令牌

安全凭证存储

与其他以纯文本存储凭据的工具不同 .env 文件，gdrive-mcp使用Bun的本机机密API安全地存储凭据：

• macOS：钥匙扣服务
• Linux：libsecret（GNOME密钥环、KWallet等）
• 视窗：Windows凭据管理器

您的OAuth凭据是：

• ✅ 由操作系统静态加密
• ✅ 受用户级访问控制保护
• ✅ 从不存储在明文配置文件中
• ✅ MCP服务器自动可用，无需环境变量

这是现代CLI工具使用的最用户友好和最安全的方法。

许可证

麻省理工学院