google-docs-mcp

google-docs-mcp

一个用于 Google Docs 的只读Model Context Protocol 服务。 它的作用是向 AI 助手（Claude 或任意 MCP 客户端）详细说明文档的评论： 每条评论的作者、时间、对应的文本、是否处于未解决或已解决状态、完整的回复串， 以及解决评论的人。

• 从设计上就是只读的。 它只请求 documents.readonly 和 drive.readonly 权限范围。没有任何工具 可以创建、编辑、解决或删除内容，并且每个工具都标记为 readOnlyHint: true。
• OAuth 2.0 登录。 用户通过桌面应用流程和 PKCE，使用自己的 Google 账号进行身份验证。 令牌保存在本地并自动刷新。
• 助手无需配置。 工具接受文档 ID 或完整的 Google Docs URL。

由 José Antonio Garrido 构建。我会在自己的博客上介绍我构建的开发者工具： josegarrido.dev。

工具

示例：list_comments

# Q4 project plan
- Document ID: `1AbC...`
- Link: https://docs.google.com/document/d/1AbC.../edit
- Owner: Ana <[email protected]>
- Last modified: 2026-09-22 08:00 UTC by Jose <[email protected]> (you)

## Comments (all): 2

### [1] 🟢 OPEN — Ana <[email protected]> · 2026-09-22 08:00 UTC

**Quoted text (what the comment refers to):**
> delivery date

**Surrounding paragraph (#7):**
> The delivery date will be shared with the client once the scope is final.

**Comment:**
The delivery date is missing.

_No replies yet._

Comment ID: `AAAAxyz`

### [2] ✅ RESOLVED — Ana <[email protected]> · 2026-09-20 10:32 UTC
...
**Thread (2 replies):**
  - Jose <[email protected]> (you) · 2026-09-21 09:00 UTC: Yes, moving it.
  - Jose <[email protected]> (you) · 2026-09-21 12:00 UTC — marked as RESOLVED

Resolved by Jose <[email protected]> (you) on 2026-09-21 12:00 UTC.

快速开始

前置条件

• Node.js >= 20
• 已启用Google Drive API 和 Google Docs API 的 Google Cloud 项目

1. 在 Google Cloud 中创建 OAuth 客户端

1. 打开 Google Cloud Console 并创建或选择一个项目。
2. API 和服务 → 库：启用 Google Drive API 和 Google Docs API。
3. API 和服务 → OAuth 同意屏幕：完成配置。对于 Workspace 组织，选择 内部；对于处于测试模式的 外部应用，将你的账号添加为测试用户。
4. API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID，应用类型选择桌面应用。
5. 下载 JSON，并将其保存为 ~/.config/google-docs-mcp/credentials.json。

也可以使用环境变量，而不使用文件：

export GOOGLE_CLIENT_ID="...apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="..."

2. 使用 Google 账号登录

npx -y -p @yeyo11/google-docs-mcp google-docs-mcp-auth

浏览器会打开（或者终端会显示 URL，供你复制粘贴）。Google 会请求访问 Drive 和 Docs 的只读权限。令牌会以 0600 权限保存到 ~/.config/google-docs-mcp/token.json。再次运行相同的命令 即可切换账号。

3. 将服务注册到 MCP 客户端

无需克隆或构建；npx 会在首次使用时获取软件包。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@yeyo11/google-docs-mcp"]
    }
  }
}

Claude Code：

claude mcp add google-docs -- npx -y @yeyo11/google-docs-mcp

任何支持 stdio 服务的其他 MCP 客户端也都可以采用相同的方式。如果使用环境变量配置 OAuth 客户端，请将它们添加到客户端配置的 env 块中。

git clone https://github.com/yeyo11/google-docs-mcp.git
cd google-docs-mcp
npm install
npm run build
npm run auth

4. 开始提问

“总结 https://docs.google.com/document/d/…/edit 中未解决的评论，并告诉我哪些评论正在等待我处理。”

配置

工作原理

MCP client ──stdio──▶ google-docs-mcp ──OAuth2 (read-only)──▶ Google Drive API (files, comments)
                                                            └▶ Google Docs API (document text)

• 评论通过 Drive API（comments.list / comments.get）获取，并显式请求每个字段，因此不会静默遗漏任何内容：引用文本、回复、resolve / reopen 操作、已删除标记。
• “周围段落”通过在从 Docs API 获取的文档正文中查找引用文本来定位（会遍历所有标签页，包括表格）。
• Google API 错误（401/403/404/429）会作为附带可执行提示的 MCP isError 结果返回，而不会中断会话。日志输出到 stderr；stdout 保留用于协议通信。

开发

npm run dev        # run the server from src/ with tsx
npm run typecheck  # type-check without emitting
npm test           # smoke test: tool listing, error handling without credentials, comment formatting

有关工作流和提交约定，请参阅 CONTRIBUTING.md。

安全

• 仅请求只读权限范围；Google 不会授予此客户端写入权限。
• 如果存储的令牌缺少所需的权限范围，服务将拒绝使用该令牌，并提示你重新登录。
• credentials.json 和 token.json 已加入 git 忽略列表。切勿提交它们。
• 如需撤销访问权限，请前往 https://myaccount.google.com/permissions 移除该应用，并删除 token.json。

如需报告漏洞，请参阅 SECURITY.md。

限制（v0.1）

• 只读：无法创建、回复或解决评论。
• 每次安装仅支持一个 Google 账号（使用 npm run auth 切换）。
• 周围段落通过搜索引用文本来定位；如果评论发布后该文本经过编辑，可能无法找到。

路线图

• 添加可选写入工具（回复、解决），须明确选择相应权限范围
• 支持多个账号 / 配置文件
• 为远程部署提供 Streamable HTTP 传输

许可证

MIT