内容
<h1 align="center">gdocs-comments-mcp</h1>
<p align="center">
<b>谷歌文档的内联、范围锚定评论 - 谷歌API无法实现的评论操作。</b>
</p>
<p align="center">
<a href="https://github.com/stanislawherjan1/gdocs-comments-mcp/actions/workflows/ci.yml"><img src="https://github.com/stanislawherjan1/gdocs-comments-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.npmjs.com/package/gdocs-comments-mcp"><img src="https://img.shields.io/npm/v/gdocs-comments-mcp?color=cb3837&logo=npm" alt="npm version"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
<img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen?logo=node.js" alt="node >= 18">
<img src="https://img.shields.io/badge/MCP-stdio-8A2BE2" alt="MCP stdio">
</p>
<p align="center">
<sub>
<a href="#quickstart">快速开始</a>
·
<a href="#what-this-does--and-what-it-doesnt">范围</a>
·
<a href="#tools">工具</a>
·
<a href="#configuration">配置</a>
·
<a href="#how-it-works">工作原理</a>
·
<a href="#troubleshooting">故障排除</a>
·
<a href="#running-on-a-server--datacenter-ip">服务器部署</a>
·
<a href="#faq">常见问题</a>
</sub>
</p>
您正在构建一个围绕谷歌文档的AI流程 - 一个审查草稿、审计合同、提供编辑反馈的代理。交付反馈的自然方式就像人类一样：**评论固定在它所评论的确切句子上**，而不是在文档末尾或聊天中倒入一堆文字。
然后您遇到了一个障碍：**谷歌API无法创建锚定评论**。Docs API根本没有评论端点，而Drive API接受一个`anchor`字段，但却忽略了它 - 评论显示为一个普通的整个文档评论。
这个MCP服务器弥补了这一空白。您的代理调用`add_comment`并附上一个文本片段和评论；服务器通过一个真实的、登录的谷歌文档会话发布它，因此它固定在确切的文本上 - 就像人类选择它并按`Ctrl+Alt+M`一样：
<p align="center">
<img src="https://raw.githubusercontent.com/stanislawherjan1/gdocs-comments-mcp/main/assets/demo.png" alt="A Google Doc with two inline comments posted by the agent, each anchored to a highlighted text fragment" width="900">
</p>
## 为什么不使用官方API？
这个服务器只做一件事：**向谷歌文档添加评论**。有趣的情况是锚定评论 - 固定在特定的文本范围内 - 而这是任何谷歌API都无法做到的。
| 添加评论… | 谷歌文档API | 谷歌Drive API | 此服务器 |
|---|:---:|:---:|:---:|
| 无锚定（整个文档） | ❌ | ✅ | ✅ |
| 锚定到文本范围 | ❌ | ❌ | ✅ |
Docs API根本没有评论端点。Drive API的`comments.create`接受一个`anchor`字段，但Docs编辑器**忽略**它 - 评论呈现为一个无锚定的整个文档评论。编辑器的锚定格式（`kix.*`）是未公开的，无法从外部生成（[Drive API文档](https://developers.google.com/workspace/drive/api/guides/manage-comments)，[issuetracker #292610078](https://issuetracker.google.com/issues/292610078)，自2016年起开放）。驱动编辑器UI是唯一的方法 - 所以这个服务器做到了这一点，而其他什么都不做。（使用Drive API的`comments.*`端点已经可以列出、回复、解决和删除评论 - 使用基于Drive的工具来完成这些操作。）
## 快速开始
**一条命令** - 登录（打开浏览器一次），然后使用Claude Code注册服务器：
```bash
npx -y gdocs-comments-mcp setup
```
就这样 - 跳到下面的**使用它**。如果您更喜欢手动操作或使用其他客户端？下面的手动步骤如下。
<details>
<summary><b>手动设置</b></summary>
**1. 登录一次** - 打开浏览器窗口；谷歌会话保存到本地配置文件（`~/.gdocs-comments-mcp/profile`）：
```bash
npx -y gdocs-comments-mcp login
```
**2. 将服务器添加到您的MCP客户端：**
```bash
# Claude Code
claude mcp add gdocs-comments -- npx -y gdocs-comments-mcp
```
**其他MCP客户端** - 在`login`后，为您的客户端添加配置：
<details>
<summary><b>Claude Desktop / Cowork</b></summary>
将以下内容添加到`claude_desktop_config.json`（设置→开发者→编辑配置）：
```json
{
"mcpServers": {
"gdocs-comments": {
"command": "npx",
"args": ["-y", "gdocs-comments-mcp"]
}
}
}
```
</details>
<details>
<summary><b>项目级<code>.mcp.json</code>（与团队通过git共享）</summary>
在项目根目录下创建`.mcp.json` - Claude Code、Cowork和大多数MCP客户端都可以使用：
```json
{
"mcpServers": {
"gdocs-comments": {
"command": "npx",
"args": ["-y", "gdocs-comments-mcp"]
}
}
}
```
注意：项目中的每个用户仍然需要在自己的机器上运行一次`npx gdocs-comments-mcp login` - 会话是个人化的，从不通过git共享。
</details>
<details>
<summary><b>Cursor</b></summary>
将以下内容添加到`.cursor/mcp.json`（项目）或`~/.cursor/mcp.json`（全局）：
```json
{
"mcpServers": {
"gdocs-comments": {
"command": "npx",
"args": ["-y", "gdocs-comments-mcp"]
}
}
}
```
</details>
<details>
<summary><b>VS Code（GitHub Copilot）</b></summary>
将以下内容添加到`.vscode/mcp.json`:
```json
{
"servers": {
"gdocs-comments": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gdocs-comments-mcp"]
}
}
}
```
</details>
</details>
**3. 使用它** - 问您的代理：
> 在https://docs.google.com/document/d/1AbC…/edit中添加评论 - 将其锚定到“quarterly numbers”并说“在星期五前更新它”。
代理调用`add_comment`并返回：
```json
{ "ok": true, "anchored": true, "occurrence_used": 1, "verified": true }
```
…and评论位于文档中您登录的帐户所选的突出显示的短语上。
不需要Playwright浏览器下载 - 默认情况下，服务器通过`playwright-core`驱动您已安装的Google Chrome。
## 工具
### `add_comment`
| 参数 | 必需 | 描述 |
|---|:---:|---|
| `doc` | ✅ | 文档ID **或** 完整的`docs.google.com/document/d/<id>/edit` URL |
| `comment_text` | ✅ | 评论正文（纯文本，新行OK） |
| `find_text` | — | 要锚定的确切单行文本片段（必须与文档文本匹配）。 **省略以添加整个文档的一般、无锚定评论。** |
| `occurrence` | — | 当`find_text`出现多次时，锚定到第N个匹配项（默认为1） |
返回 `{ ok, anchored, occurrence_used, verified }` - `verified: true` 表示发布的评论在提交后被观察到。 如果`find_text`给定但未找到，则调用失败并返回`TEXT_NOT_FOUND`，并且**不会发布任何内容**。
该工具 **从不返回文档内容**，因此恶意文档无法通过它将指令注入到您的代理中。
### `check_connection`
探测谷歌会话；返回 `{ connected, mode }`。如果`connected: false`，请再次运行 `npx gdocs-comments-mcp login`。
> **范围说明：** 此服务器只做一件事 - 创建锚定评论。 使用Drive API的`comments.*`端点可以列出、回复、解决和删除评论，这些操作都很快，不需要浏览器 - 使用基于Drive的MCP来完成这些操作。
## CLI
```bash
npx gdocs-comments-mcp login # 一次性交互式谷歌登录
npx gdocs-comments-mcp status # 保存的会话是否仍然有效？
npx gdocs-comments-mcp logout # 删除保存的会话/配置文件
```
## 配置
所有配置项均为可选，通过环境变量：
| 环境变量 | 默认值 | 用途 |
|---|---|---|
| `GDOCS_COMMENTS_PROFILE_DIR` | `~/.gdocs-comments-mcp/profile` | 登录浏览器配置文件的位置（每个谷歌帐户设置不同的目录） |
| `GDOCS_COMMENTS_BROWSER_CHANNEL` | `chrome` | `chrome` \| `msedge` \| `chromium`（捆绑；需要 `npx playwright install chromium`） |
| `GDOCS_COMMENTS_HEADLESS` | `true` | 设置为 `false` 以查看自动化操作 |
| `GDOCS_COMMENTS_IDLE_CLOSE_MIN` | `10` | 在N分钟空闲后关闭托管浏览器（`0` = 保持打开） |
| `GDOCS_COMMENTS_CDP_URL` | — | 通过CDP附加到现有的浏览器而不是管理配置文件（[见下文](#running-on-a-server--datacenter-ip）） |
| `GDOCS_COMMENTS_AUDIT_LOG` | off | JSONL审计日志（仅哈希值，无内容） |
## 故障排除
| 错误 | 含义 | 修复 |
|---|---|---|
| `NOT_CONNECTED` | 尚未保存谷歌会话 | `npx gdocs-comments-mcp login` |
| `SESSION_EXPIRED` | 保存的会话已过期（空闲会话后约1-2周） | 再次运行 `npx gdocs-comments-mcp login` |
| `TEXT_NOT_FOUND` | `find_text`在文档中不出现（或`occurrence` > 匹配数） | 传输入的片段与文档文本完全匹配 - 没有发布任何内容 |
| `NO_BROWSER` | 未找到Chrome/Edge/Chromium | 安装Google Chrome，或 `npx playwright install chromium` + `GDOCS_COMMENTS_BROWSER_CHANNEL=chromium` |
| `PROFILE_LOCKED` | 另一个进程持有配置文件（通常是运行的服务器 + `login`/`status`尝试） | 停止其中一个，或使用第二个`GDOCS_COMMENTS_PROFILE_DIR` |
| 评论落地但 `verified: false` | 提交后检查无法看到评论（可能是长评论的假阴性） | 检查文档；重新运行 `GDOCS_COMMENTS_HEADLESS=false` 观看 |
首次在新机器上运行？ `npx gdocs-comments-mcp status` 告诉您确切的位置。
## 在服务器/数据中心IP上运行
在住宅机器上，默认配置文件模式直接有效。在数据中心IP上，谷歌的反欺诈机制 **拒绝从新启动的浏览器进程重用保存的会话** - 它会跳转到 `accounts.google.com/confirmidentifier`。从配置文件启动不起作用。
有效的方法是保持操作员登录的浏览器 **alive**，并让服务器通过CDP附加到它：
1. 启动一个长期运行的Chrome/Chromium（在Xvfb下无头）并启动 `--remote-debugging-port=9333`，并在其中登录谷歌。
2. 运行MCP服务器 `GDOCS_COMMENTS_CDP_URL=http://127.0.0.1:9333`。
然后服务器通过CDP驱动该实时会话，从不启动自己的浏览器。 通过导航到 `docs.google.com` 每隔几个小时保持会话热，空闲会话后约1-2周过期。
## 工作原理
由于API无法锚定评论，因此服务器做的正是人们所做的：驱动真正的谷歌文档编辑器。以下是 `add_comment` 调用执行的完整流程。
**1. 附加到登录的浏览器**。在默认 **配置文件模式** 下，服务器拥有一个持久的Chromium配置文件（您的安装的Google Chrome，通过 `playwright-core` - 无需额外的浏览器下载）。您通过 `gdocs-comments-mcp login` 进行身份验证；谷歌会话cookie保存到 `~/.gdocs-comments-mcp/profile` 并在以后每次运行时重用无头模式。在 **CDP模式** (`GDOCS_COMMENTS_CDP_URL`)，服务器改为通过Chrome DevTools协议附加到您保持活跃的浏览器 - [服务器部署](#running-on-a-server--datacenter-ip)。
**2. 打开文档。** 它导航到 `https://docs.google.com/document/d/<id>/edit?hl=en`。 文档ID首先被验证，并且导航硬固定为 `docs.google.com` - 工具不能被转向其他站点。如果页面跳转到 `accounts.google.com`，则会话已死亡，调用返回 `SESSION_EXPIRED`。 `?hl=en`固定UI语言，以便在下一步中查找计数器是可解析的。
**3. 查找锚定文本。** 文档主体渲染到一个HTML `<canvas>`，不可选择的DOM - 所以不能直接查询文本并单击它。相反，流程完全是键盘驱动的（也使它与locale和CSS类无关）：
```
Ctrl/Cmd+F → type find_text → read the "N of M" match counter```
阅读计数器 **之前**评论是关键的安全步骤：如果 `find_text`有零个匹配项，或 `occurrence` 大于匹配项计数，则调用失败并返回 `TEXT_NOT_FOUND`， → Esc → Ctrl/Cmd+Alt+M → type → Ctrl/Cmd+Enter (submit)
```
`Ctrl/Cmd+Alt+M` 是Docs的快捷键，用于“在当前选择上插入评论” - 这正是API无法创建的锚定评论。快捷键根据平台进行选择（在macOS上使用`Cmd`，在其他地方使用`Ctrl`）。
（如果省略`find_text`，步骤3-4简化为“将光标放在文档开头并评论” - 一个常规的、无锚定的评论。）
**4. 验证并报告。** 提交后，服务器等待评论文本出现在页面上，并返回 `{ ok, anchored, occurrence_used, verified }`。`verified: true` 表示发布的评论实际上被观察到了；它永远不会返回任何文档内容，因此中毒文档无法通过此工具将指令偷偷带回您的代理。并发调用在互斥锁后面序列化，因为同一个窗口中的两个键盘流程会互相交织并损坏彼此。
```
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更不稳定。** 如果谷歌重新设计编辑器，此功能可能会损坏，直到更新。`verified` 标志告诉您评论是否实际发布；欢迎报告UI更改的贡献。
- 登录帐户需要 **评论访问** 目标文档。
- `find_text` 必须是 **单行** 片段（查找栏为一行），并且必须与文档文本完全匹配。
- 未使用的会话在大约1-2周后过期；`status` 告诉你，`login` 修复它。
- 调用是序列化的，因此批量评论按设计顺序进行（通常每个评论几秒钟）。
- 使用您自己的帐户通过其正常界面自动化Google帐户是您对Google服务条款的责任。 使用您自己的帐户；不要使用此功能进行垃圾邮件发送。
## 安全
**AI代理（和MCP客户端）可以看到的内容。** 没有敏感信息。登录时，您直接在谷歌浏览器中输入谷歌凭证 - 登录步骤是一个终端CLI， **不是** MCP工具，因此模型永远不会进入该循环，并且永远不会看到您的密码、2FA、cookie或OAuth令牌。在正常使用过程中，`add_comment`和`check_connection`工具仅返回 **结构化状态** (`{ ok, anchored, occurrence_used, verified }` / `{ connected, mode }`) 并且 **永远不会返回任何文档内容** - 因此中毒文档无法通过此工具将指令偷偷带回模型。唯一进入模型上下文的内容是代理本身提供的内容（`doc`, `find_text`, `comment_text`）和偶尔的本地文件路径在错误消息中。
**敏感材料存储位置。** 您的 **谷歌会话cookie** 位于配置文件目录中 (`~/.gdocs-comments-mcp/profile`)，权限为 `0700` - 将此目录视为密码。它保留在磁盘上，永远不会返回给模型。`logout` 删除它；您也可以通过 [谷歌设备活动](https://myaccount.google.com/device-activity) 在服务器端撤销它。可选的审计日志仅存储 **哈希值**，而非内容。剩余风险是普通本地机器卫生：任何其他进程具有读取访问配置文件目录的权限，都可能重用会话 - 这不是MCP数据流，只是标准的本地安全性。
**遏制。** 文档ID严格验证，导航硬固定为 `docs.google.com` - 工具不能被引导到其他站点。
## 常见问题
**谷歌文档API或Drive API能否创建特定文本范围内的锚定评论？**
不。谷歌文档API没有评论端点，Drive API的`comments.create`接受一个`anchor`字段，该字段被Docs编辑器忽略 - 评论呈现为一个无锚定的整个文档评论。本项目专门用于解决这个问题。参见 [为什么不使用官方API？](#%e4%b8%ba%e4%bb%80%e4%b9%88%e4%b8%8d%e4%bd%bf%e7%94%b0%e5%ae%98%e6%96%b9api%ef%bc%9f)。
**如何编程为谷歌文档添加内联/锚定评论？**
使用此MCP服务器，或它使用的技术：驱动Docs编辑器UI（查找文本，按 `Ctrl+Alt+M`）而不是调用REST API。 [工作原理](#%e5%b7%a5%e4%bd%90%e5%ae%9e%e7%94%b5) 记录完整的流程。
**我如何让AI代理（Claude，Cursor，Copilot）评论谷歌文档？**
将此服务器添加到您的MCP客户端（[快速开始](#%e5%bf%ab%e9%80%9f%e5%bc%80%e5%a7%8b）并获得一个`add_comment`工具，该工具发布真正的锚定评论 - 适用于AI文档审查，合同/编辑反馈和自动校对工作流。
**我需要谷歌云项目，OAuth客户端或服务帐户吗？**
不需要。身份验证是一次性交互式浏览器登录（`gdocs-comments-mcp login`）使用您的普通谷歌帐户 - 无需API凭证，无需OAuth同意屏幕，无需服务帐户设置。
**它是否适用于谷歌工作区/共享驱动器/评论者访问权限？**
是的，只要登录的帐户对文档具有至少评论权限即可。
**我可以在服务器或CI中运行它吗？**
是的 - [在服务器/数据中心IP上运行](#%e8%bf%90%e8%a1%8c%e4%ba%98%e6%9c%8d%e5%90%af%e6%9c%8d%e5%90%af%e6%9c%8d-ip)。在数据中心IP上，您通过CDP附加到一个长寿命的已登录浏览器，而不是重新启动一个。
## 贡献
欢迎提交问题和PR，特别是关于Docs UI更改的报告，这些更改会破坏键盘流程（请包括您的本地化和`verified`是否为`false`）。纯ESM，无需构建步骤：`git clone`，`npm install`，`node src/cli.js`。
## 许可证
[MIT](LICENSE) © Stanisław Herjan
---
<sub><b>关键词：</b> 谷歌文档锚定评论 · 内联评论谷歌文档API · 编程添加评论到谷歌文档 · 谷歌文档评论API变通方法 · MCP服务器谷歌文档 · 模型上下文协议 · Claude / Cursor / Copilot谷歌文档集成 · AI文档审查 · Playwright谷歌文档自动化 · 评论谷歌文档文本范围。</sub>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器