google-drive-comments-mcp

google-drive-comments-mcp

一个专注于读取 Google Drive 文件评论的 Model Context Protocol 服务（也提供独立 CLI），支持 Docs、Sheets 和 Slides。只有两个工具，使用只读 OAuth 权限，不提供其他功能。

开发此服务是因为托管的 Google Drive 连接器支持读取文件内容和搜索，却无法读取评论串——包括评审讨论、引用锚定文本以及解决/重新打开历史记录。此服务为任何 MCP 客户端（Claude Code、Claude Desktop、Cursor、Cline 等）填补了这一空白，也可作为普通 CLI 使用。

功能

• 2 个 MCP 工具 — drive_search_files、drive_get_comments。这就是全部 API。
• 读取完整评论串 — 作者、内容、锚定的引用文本、已解决/未解决状态，以及所有回复（包括解决/重新打开操作）。
• 支持 Docs、Sheets 和 Slides — Drive 评论 API 在各种文件类型中的用法相同。
• 接受 URL 或 ID — 粘贴 docs.google.com/document/d/… 链接或直接输入文件 ID。
• 只读 OAuth 权限（drive.readonly）。
• 通过环境变量配置 — DRIVE_MCP_CREDENTIALS、DRIVE_MCP_TOKEN、DRIVE_MCP_SCOPES。

安装

pip install google-drive-comments-mcp
# or, with uv:
uv tool install google-drive-comments-mcp

一次性设置（约 10 分钟）

你需要一个 Google Cloud OAuth 客户端。服务完全在你的计算机上运行，不会有任何数据离开本机。

1. 使用你要读取其 Drive 评论的账号登录 Google Cloud Console。
2. 创建一个项目（或选择现有项目）。
3. 启用 Drive API：console.cloud.google.com/apis/library/drive.googleapis.com。
4. 在 APIs & Services → OAuth consent screen 下配置 OAuth 同意屏幕：
   • Google Workspace 用户：用户类型 = Internal。即使 drive.readonly 是受限权限，也无需验证应用。
   • 个人 Gmail 用户：用户类型 = External，并在“Test users”下添加你自己的地址。
5. APIs & Services → Credentials → + Create credentials → OAuth client ID
   • 应用类型：Desktop app
   • 下载 JSON 文件。
6. 运行设置：

google-drive-comments-mcp setup --import-credentials ~/Downloads/client_secret_*.json

浏览器窗口会打开，用于 OAuth 授权。刷新令牌会缓存到 ~/.config/google-drive-comments-mcp/token.json。

验证：

google-drive-comments-mcp status
google-drive-comments-mcp comments "https://docs.google.com/document/d/YOUR_DOC_ID/edit"

在 Claude Code 中使用

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

然后：

读取这份文档中未解决的评论，并总结评审者提出的要求：https://docs.google.com/document/d/…

在 Claude Desktop 中使用

~/Library/Application Support/Claude/claude_desktop_config.json（Mac）：

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

（如果 Claude Desktop 的 $PATH 中没有该命令，请使用 which google-drive-comments-mcp 获取绝对路径。）

在 shell 中使用

# Find a doc
google-drive-comments-mcp search "Q3 strategy"

# Read all comments (open + resolved) on a doc by URL or ID
google-drive-comments-mcp comments "https://docs.google.com/document/d/abc123/edit"

# Only unresolved comments
google-drive-comments-mcp comments abc123 --open-only

2 个 MCP 工具

drive_search_files(query, max_results=10)

搜索 Drive。普通字符串会自动转换为文件名搜索；原始 Drive 查询语法则会原样传递。

[
  {
    "id": "1AbC…",
    "name": "Q3 Strategy",
    "mime_type": "application/vnd.google-apps.document",
    "modified": "2026-04-20T09:00:00.000Z",
    "owners": ["Jane Doe"],
    "web_view_link": "https://docs.google.com/document/d/1AbC…/edit"
  }
]

drive_get_comments(file, include_resolved=True)

读取文件上的所有评论。file 可以是 Docs/Sheets/Slides/Drive URL 或直接填写文件 ID。

{
  "file": { "id": "1AbC…", "name": "Q3 Strategy", "mime_type": "…document", "web_view_link": "…", "owners": ["Jane Doe"] },
  "open_count": 2,
  "resolved_count": 1,
  "comments": [
    {
      "id": "AAAA…",
      "author": "Jane Doe",
      "content": "Can we add the unit-economics table here?",
      "quoted_text": "Our margins improved in Q3.",
      "resolved": false,
      "created": "2026-04-21T10:00:00Z",
      "modified": "2026-04-21T10:00:00Z",
      "replies": [
        { "author": "John Smith", "content": "Added.", "action": "", "created": "2026-04-21T11:00:00Z" }
      ]
    }
  ]
}

quoted_text 是评论所锚定的文档文本，有助于理解每条评论的指向。

配置

变量	默认值	说明
DRIVE_MCP_CREDENTIALS	~/.config/google-drive-comments-mcp/credentials.json	OAuth 客户端密钥 JSON
DRIVE_MCP_TOKEN	~/.config/google-drive-comments-mcp/token.json	缓存的刷新令牌
DRIVE_MCP_SCOPES	https://www.googleapis.com/auth/drive.readonly	OAuth 权限范围（逗号分隔）
XDG_CONFIG_HOME	~/.config	标准 XDG 覆盖项

与其他 Google MCP 工具共享一个登录

如果你还运行了一个同系列工具（例如 gmail-attachments-mcp），并希望两个工具共用一次 OAuth 授权，请让两个工具指向相同的凭据文件和令牌文件（通过上文中的环境变量或符号链接），然后使用合并后的权限范围授权一次：

DRIVE_MCP_SCOPES="https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/drive.readonly" \
  google-drive-comments-mcp setup --reauth

获准权限范围为其他工具所需权限范围的超集的令牌，也能满足各工具较窄的请求。

安全性

• 只读：默认权限范围为 drive.readonly。它无法编辑、评论或删除内容，只能读取文件元数据、内容和评论。
• 权限范围广泛：drive.readonly 可读取你云端硬盘中的所有文件，而不仅仅是你查询的文件。没有既能读取单个文件、又能访问评论的权限范围。请像对待密码一样保护缓存的令牌（写入时权限为 0600）。
• 无遥测：你的 OAuth 客户端位于你自己的 Google Cloud 项目中。任何数据都不会离开你的计算机。

故障排查

HttpError 403: Google Drive API has not been used in project … before or it is disabled
在拥有你的 OAuth 客户端的项目中启用 Drive API，然后重试。

Claude Desktop / cron 报错 No valid Google token
在可以打开浏览器的终端中运行一次 google-drive-comments-mcp setup。后续运行会复用缓存的令牌。

你确认文件中有评论，但返回的评论为空
确认你授权的账号确实可以查看该文件，并且文件中确实有评论（建议不是评论）。除非传入 --open-only / include_resolved=false，否则会包含已解决的评论。

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

没有 API 密钥，也没有随软件提供的机密信息。该服务使用你创建的 OAuth 客户端向 你的 Google 账号进行身份验证，并在本地缓存刷新令牌。作者无法访问你的任何数据。

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

更多指南

• docs/setup-google-oauth.md — 完整的 OAuth 指南及常见错误
• docs/claude-code.md · docs/claude-desktop.md · docs/other-clients.md — 各客户端的配置说明（Cursor、Cline、Continue 等）
• examples/ — 可运行的代码片段

相关工具

这是一个小型工具集的一部分，包含一系列专注于本地处理 Google Workspace 数据的 MCP 服务，可访问托管连接器未提供的数据：

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

它们可以共用一个 OAuth 登录，也可以彼此隔离 — 请参阅各仓库中的配置说明。

许可证

MIT。请参阅 LICENSE。