gdocs-comments-mcp

gdocs-comments-mcp

为 Google Docs 提供内联、范围锚定的评论——这是 Google API 无法完成的唯一评论操作。

_{快速开始  ·  适用范围  ·  工具  ·  配置  ·  工作原理  ·  故障排查  ·  服务部署  ·  常见问题}

你正在围绕 Google Docs 构建 AI 流程——一个审阅草稿、审核合同、提供编辑反馈的 Agent。传递这些反馈最自然的方式，就是像人类那样：将评论固定在对应的确切句子上，而不是把一大段文字堆在文档末尾或聊天中。

然后你就会碰壁：Google API 无法创建锚定评论。 Docs API 完全没有评论端点，而 Drive API 虽然接受 anchor 字段，Docs 编辑器却会忽略它——评论会显示为针对整个文档的普通评论。

这个 MCP 服务弥补了这一缺口。你的 Agent 使用文本片段和评论调用 add_comment；服务会通过真实的、已登录的 Google Docs 会话发布评论，将其锚定到对应文本上——就像人类选中该文本并按下 Ctrl+Alt+M 一样：

为什么不使用官方 API？

这个服务只做一件事：向 Google Doc 添加评论。 值得关注的情况是锚定评论——固定在特定文本范围上的评论——而 Google API 无法做到这一点。

Docs API 完全没有评论端点。Drive API 的 comments.create 接受 anchor 字段，但 Docs 编辑器会忽略它——评论显示为未锚定、针对整个文档的评论。编辑器自身的锚定格式（kix.*）没有文档说明，也无法通过外部方式生成（Drive API 文档，问题跟踪器 #292610078，自 2016 年起仍未解决）。唯一可行的方法是驱动编辑器 UI——因此这个服务正是这么做的，仅此而已。（列出、回复、解决和删除评论都可以通过 Drive API 实现——这些操作请使用基于 Drive 的工具。）

此工具能做什么——不能做什么

此服务刻意专注于一件小事。接入前请先阅读本文。

**✅ 它能做什么：**为 Google 文档添加评论——可锚定到特定文本范围（这是 API 做不到的部分），也可不锚定到文档全文。

❌ 它不能做什么：

重要：此工具绝不会返回文档内容——按设计，它只返回结构化数据（{ ok, anchored, occurrence_used, verified }），这样恶意文档就无法向 Agent 注入指令。这意味着 Agent 写评论时是盲写：若要智能地审阅文档，请将此工具与读取能力（Docs API documents.get）配合使用，并将引用的确切文本作为 find_text 传入。两者使用不同的身份验证方式——此服务驱动已登录的浏览器会话（无需 OAuth），而 Docs/Drive API 需要 OAuth 令牌或服务账号——但它们可以针对同一个 Google 账号运行。

快速开始

一条命令——登录（打开一次浏览器），然后向 Claude Code 注册此服务：

npx -y gdocs-comments-mcp setup

完成——接下来请跳至下方的使用方法。想手动操作，或使用其他客户端？请参阅下方的手动步骤。

npx -y gdocs-comments-mcp login

# Claude Code
claude mcp add gdocs-comments -- npx -y gdocs-comments-mcp

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "servers": {
    "gdocs-comments": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

3. 使用——向 Agent 提出请求：

为 https://docs.google.com/document/d/1AbC…/edit 添加评论——将评论锚定到“季度数据”，并写上“请在周五前更新”。

Agent 会调用 add_comment，并收到以下结果：

{ "ok": true, "anchored": true, "occurrence_used": 1, "verified": true }

……评论便会显示在文档中高亮的短语上，评论发布自你登录时使用的账号。

无需下载 Playwright 浏览器——默认情况下，此服务通过 playwright-core 驱动你已安装的 Google Chrome。

工具

add_comment

返回 { ok, anchored, occurrence_used, verified }——verified: true 表示提交后已在页面中观察到已发布的评论。如果提供了 find_text 但未找到匹配项，调用会以 TEXT_NOT_FOUND 失败，且不会发布任何内容。

此工具绝不会返回文档内容，因此恶意文档无法通过它向 Agent 注入指令。

check_connection

探测 Google 会话；返回 { connected, mode }。如果 connected: false，请再次运行 npx gdocs-comments-mcp login。

**范围说明：**此服务只做一件事——创建锚定评论。通过 Drive API（comments.*）列出、回复、解决和删除评论都没有问题，而且速度更快，也不需要浏览器——这些操作请使用基于 Drive 的 MCP。

CLI

npx gdocs-comments-mcp login    # one-time interactive Google sign-in
npx gdocs-comments-mcp status   # is the saved session still valid?
npx gdocs-comments-mcp logout   # delete the saved session/profile

配置

所有配置项均为可选，可通过环境变量设置：

故障排除

在新机器上首次运行？npx gdocs-comments-mcp status 会准确告知当前状态。

在服务器 / 数据中心 IP 上运行

在住宅网络的机器上，默认配置文件模式可以直接使用。在数据中心 IP 上，Google 的反欺诈机制会拒绝重用已保存会话的新启动浏览器进程，并跳转到 accounts.google.com/confirmidentifier。在此类环境中，从配置文件重新启动不起作用。

可行的方法是：让操作员登录时使用的那台浏览器保持运行，并让此服务连接到它：

1. 启动一个长期运行的 Chrome/Chromium（无头模式下使用 Xvfb），设置 --remote-debugging-port=9333，并在其中登录一次 Google。
2. 使用 GDOCS_COMMENTS_CDP_URL=http://127.0.0.1:9333 运行 MCP 服务。

随后，服务会通过 CDP 控制该活动会话，不会启动自己的浏览器。每隔几小时将会话导航到 docs.google.com，以保持会话活跃；否则，空闲会话会在约 1–2 周后过期。

工作原理

由于 API 无法锚定评论，服务会像真人一样操作真正的 Google Docs 编辑器。以下是一次 add_comment 调用的完整流程。

1. 连接到已登录的浏览器。 在默认的 profile mode 下，服务会管理一个持久化的 Chromium 配置文件（通过 playwright-core 使用已安装的 Google Chrome，无需额外下载浏览器）。你只需使用 gdocs-comments-mcp login 登录一次；Google 会话 Cookie 会保存到 ~/.gdocs-comments-mcp/profile，之后每次运行都会在无头模式下重复使用。在 CDP mode（GDOCS_COMMENTS_CDP_URL）下，服务会通过 Chrome DevTools Protocol 连接到你保持运行的浏览器——请参阅服务部署。

2. 打开文档。 服务会导航到 https://docs.google.com/document/d/<id>/edit?hl=en。它会先验证 doc ID，并将导航严格限制在 docs.google.com——无法通过该工具跳转到其他位置。如果页面跳转到 accounts.google.com，说明会话已失效，此次调用会返回 SESSION_EXPIRED。?hl=en 会固定界面语言，以便在下一步解析查找栏计数器。

3. 查找锚定文本。 文档正文会渲染到 HTML <canvas> 中，而不是可选择的 DOM，因此不能直接查询文本并点击。整个流程改为完全由键盘驱动（也因此不受区域设置和 CSS 类影响）：

Ctrl/Cmd+F  →  type find_text  →  read the "N of M" match counter

在添加评论之前先读取计数器，是关键的安全步骤：如果 find_text 没有匹配项，或者 occurrence 大于匹配项数量，调用就会以 TEXT_NOT_FOUND 失败，不会发布任何内容。这避免了旧版失败模式：盲目执行按键序列会悄无声息地把评论放到光标当时所在的位置。

4. 选择指定匹配项并添加评论。 服务会按 Enter N 次，定位到第 N 个匹配项，再按 Esc 关闭查找栏（同时保留该匹配项的选中状态），然后：

Ctrl/Cmd+Alt+M  →  type comment_text  →  Ctrl/Cmd+Enter (submit)

Ctrl/Cmd+Alt+M 是 Docs 中“对当前选区插入评论”的快捷键——这正是 API 无法创建的锚定评论。快捷键会根据平台选择（macOS 使用 Cmd，其他平台使用 Ctrl）。

（如果省略 find_text，第 3–4 步会简化为“将光标放到文档开头并在那里添加评论”——这是普通的非锚定评论。）

5. 验证并报告。 提交后，服务会等待评论文本出现在页面中，并返回 { ok, anchored, occurrence_used, verified }。verified: true 表示确实观察到了已发布的评论；服务绝不会返回任何文档内容，因此被投毒的文档无法向你的 Agent 偷渡指令。并发调用会通过互斥锁串行处理，因为在同一窗口中同时执行两个键盘操作流程会相互交错并导致操作出错。

add_comment ─▶ attach browser ─▶ open doc (?hl=en) ─▶ Ctrl/Cmd+F find_text
             ─▶ check match counter ─(0 matches)─▶ TEXT_NOT_FOUND, nothing posted
             ─▶ Enter×N ─▶ Esc ─▶ Ctrl/Cmd+Alt+M ─▶ type ─▶ Ctrl/Cmd+Enter
             ─▶ verify comment in page ─▶ { ok, occurrence_used, verified }

限制

• UI 自动化本质上不如 API 稳定。 如果 Google 重构编辑器，这项功能可能会暂时失效，直到更新完成。verified 标志会告诉你发布后是否确实观察到了评论；非常欢迎提交报告 UI 变化的贡献。
• 登录账号需要对目标文档拥有评论权限。
• find_text 必须是单行文本片段（查找栏只有一行），并且必须与文档文本完全匹配。
• 未使用的会话大约 1–2 周后会过期；status 会提示你，使用 login 即可修复。
• 调用会按顺序执行，因此批量添加评论默认是串行的（每条评论通常需要几秒）。
• 通过 Google 的常规界面自动操作你自己的 Google 账号，相关责任由你承担，并须遵守 Google 的服务条款。请使用自己的账号；请勿将此功能用于发送垃圾内容。

安全

AI Agent（以及 MCP 客户端）能看到什么。 没有任何敏感信息。登录是在真实浏览器中进行的，你会直接向 Google 输入 Google 凭据——login 步骤是终端 CLI，不是 MCP 工具，因此模型不会参与其中，也看不到你的密码、双重身份验证信息、Cookie 或 OAuth 令牌。正常使用时，add_comment 和 check_connection 工具只会返回结构化状态（{ ok, anchored, occurrence_used, verified } / { connected, mode }），绝不会返回任何文档内容——因此，遭到投毒的文档无法通过此工具向模型偷偷传入指令。只有 Agent 自己提供的内容（doc、find_text、comment_text）以及偶尔出现在错误消息中的本地文件路径会进入模型上下文。

敏感信息实际存放在哪里。 你的 Google 会话 Cookie 存放在配置文件目录（~/.gdocs-comments-mcp/profile）中，该目录以 0700 权限创建——请像保护密码一样保护此目录。它会保留在磁盘上，绝不会返回给模型。logout 会删除该目录；你也可以通过 Google 设备活动在服务器端撤销会话。可选的审计日志只存储哈希值，绝不存储内容。唯一残留的风险是常见的本地设备安全问题：任何有权读取该目录的其他进程都可能复用此会话——这不是 MCP 数据流问题，只是标准的本地安全问题。

限制范围。 文档 ID 会经过严格验证，且导航被严格限定在 docs.google.com——无法将此工具引导至其他网站。

常见问题

Google Docs API 或 Drive API 能否在特定文本范围内创建锚定评论？ 不能。Google Docs API 没有评论端点，而 Drive API 的 comments.create 虽接受 anchor 字段，但 Docs 编辑器会忽略该字段——评论会显示为未锚定的整篇文档评论。本项目正是为解决此问题而创建的。请参阅为什么不用官方 API？。

如何以编程方式向 Google Docs 添加行内评论／锚定评论？ 使用此 MCP 服务，或使用其采用的相同技术：通过操作 Docs 编辑器界面（查找文本，按 Ctrl+Alt+M），而不是调用 REST API。工作原理介绍了完整流程。

如何让 AI Agent（Claude、Cursor、Copilot）评论 Google Docs？ 将此服务添加到 MCP 客户端（快速入门），Agent 就会获得一个 add_comment 工具，可发布真实的锚定评论——非常适合 AI 文档审阅、合同／编辑反馈以及自动校对工作流。

我需要 Google Cloud 项目、OAuth 客户端或服务账号吗？ 不需要。身份验证只需进行一次交互式浏览器登录（gdocs-comments-mcp login），使用你的普通 Google 账号即可——无需 API 凭据、OAuth 同意屏幕或服务账号设置。

它是否适用于 Google Workspace／共享云端硬盘／仅有评论者权限的账号？ 可以，只要已登录的账号至少拥有该文档的评论权限即可。

我可以在服务器或 CI 中运行它吗？ 可以——请参阅在服务器／数据中心 IP 上运行。在数据中心 IP 上，你需要通过 CDP 连接到一个长期保持登录状态的浏览器，而不是重新启动浏览器。

参与贡献

欢迎提交 Issue 和 PR——尤其欢迎报告会导致键盘操作流程失效的 Docs 界面变更（请注明你的语言区域，以及 verified 是否为 false）。使用纯 ESM，无需构建：git clone、npm install、node src/cli.js。

许可证

MIT © Stanisław Herjan

_{关键词：Google Docs 锚定评论 · Google Docs API 行内评论 · 以编程方式向 Google Docs 添加评论 · Google Docs 评论 API 替代方案 · Google Docs MCP 服务 · Model Context Protocol · Claude / Cursor / Copilot 与 Google Docs 集成 · AI 文档审阅 · Playwright Google Docs 自动化 · 对 Google Docs 文本范围发表评论。}