Google Docs MCP

Google Docs MCP

English | Русский

A1 Google Docs MCP 可让 AI 应用用自然语言读取和编辑 Google Docs。你可以将文档读取为文本或 Markdown，修改指定段落，设置标题、列表和表格的样式，处理评论线程，并将结果导出为 PDF 或 DOCX。

它通过你的 Google 账号使用 Google Docs API。它依据精确的索引范围进行编辑，而非凭空猜测；同时会明确说明 Docs API 的限制，不会让人误以为所有文档操作都能实现。

• 27 个工具。 将文档读取为文本、结构或 Markdown，编辑精确范围，设置字符和段落样式，管理列表、表格、分隔符、图片和评论线程，并导出为 PDF、DOCX 等格式。
• 在对话中连接。 只需说“连接 Google Docs”：服务会引导你设置 OAuth 客户端，通过 PKCE 在 127.0.0.1 捕获 Google 的重定向，并自行保存令牌——无需配置文件，也无需重启。
• 精准编辑。 更改针对精确的索引范围；由于每次更改都会使后续索引发生偏移，服务会引导助手在每次编辑前重新读取文档。
• 双向支持 Markdown。 可从 Markdown 创建文档，也可将文档导出为 Markdown、PDF、DOCX 等格式；用 Markdown 替换整个文档是单独的、明确标注为破坏性的操作。
• 不暴露隐藏的 Drive 功能。 导出、Markdown 转换和评论在内部使用 Drive 端点，但服务不会提供通用的 Drive 工具。

先从只读问题开始：

阅读启动计划文档，并总结其中尚未解决的评论线程。

连接服务 · 探索使用场景 · 查看技术文档

一分钟了解它的工作方式

你： 显示启动计划文档的文本和评论。

助手： 将文档读取为精简文本块，并列出其中的评论线程。不会修改任何内容。

你： 重写“时间安排”段落，说明 Beta 版将于 3 月 3 日开始。

助手： 显示要替换的精确范围和建议文本，然后在编辑前征求确认。

你： 确认。

助手： 替换该范围。文档其余部分、格式和评论均保持不变。

目录

• 快速开始
• 你可以让它做什么
• 文档如何更改
• 可以更改的内容
• 获取访问权限
• 配置
• 数据、限制和后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+ 和一个 Google 账号。安装时无需凭据——服务会在对话中连接。

1. 将服务添加到你的 AI 应用。
2. 说“连接 Google Docs”：助手会引导你创建 OAuth 客户端并批准访问权限，无需编辑配置文件。
3. 提出上面的只读问题。

codex mcp add google-docs \
  -- npx -y @a1-x-tech/mcp-google-docs@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-docs \
  -- npx -y @a1-x-tech/mcp-google-docs@latest

claude mcp list

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-docs@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-docs@latest"]
    }
  }
}

{
  "servers": {
    "google-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-docs@latest"]
    }
  }
}

你可以让它做什么

阅读和导出文档

• 将此文档作为包含标题和表格的文本读取，并进行总结。
• 显示手册文档的标签页树。
• 将规范导出为 Markdown；将合同保存为 PDF 文件。

编写和编辑文本

• 根据此 Markdown 创建一份会议记录文档。
• 在引言后插入一段摘要。
• 在整个文档中将每个 “Q3” 替换为 “Q4”。
• 删除过时的定价部分。

格式和结构

• 将这些段落转换为编号列表；将这一行设为二级标题。
• 将关键术语加粗，并链接到术语表。
• 为路线图插入一个 3×4 表格，并填充标题行。
• 在附录前添加分页符；插入一张来自公开 URL 的图片。

处理评论

• 列出尚未解决的评论串并进行总结。
• 回复有关截止日期的评论，并将其标记为已解决。
• 添加一条评论，并引用需要法律审核的句子。

文档如何变化

1. create_document 会创建一个文档——可以是空文档，也可以在一次调用中由 Markdown 转换而成。
2. 内容通过索引定位——即标签页正文中的 UTF-16 位置；每次插入或删除都会移动后续所有索引。服务会引导助手在每次编辑前通过 read_document_text 获取最新索引，并从文档末尾向前编辑。
3. import_markdown 会替换整个正文：评论锚点、定位对象、页眉／页脚和额外标签页在转换后都不会保留。
4. 可以读取和指定标签页，但 API 无法创建、重命名、删除或重新排序标签页。
5. 评论存储在 Drive 中，并以讨论串的形式管理。无法将新评论锚定到文本范围——锚点格式未公开——因此评论会附加在文档级别，并可选择引用其所指的文本。

导出文件大小上限为 10 MB，且不包含评论或建议。内嵌图片由 Google 从公共 URL 获取（PNG／JPEG／GIF，最大 50 MB 且不超过 25 兆像素）；没有可用于上传图片文件的渠道。

可以进行哪些更改

AI 客户端负责控制确认提示。服务会标记读取、写入和具有破坏性的工具，以便客户端区分检查与实际更改。

获取访问权限

Google Docs 需要 OAuth 2.0；仅有 API 密钥还不够。有两种接入方式，第一种不需要配置文件。

在聊天中连接（推荐）

发送“connect Google Docs”，助手就会引导你完成整个流程：

1. setup_instructions 会打印检查清单：创建或选择 Google Cloud 项目、启用 Google Docs API、配置同意屏幕并创建 Desktop app OAuth 客户端。
2. 下载该客户端的 JSON（“Download JSON”），并将其路径提供给助手——set_client 会以仅所有者可访问的权限保存它。密钥绝不会经过对话传输。
3. start_login 会返回 Google 授权链接。在这台机器上打开链接并批准；验证码会返回到 127.0.0.1 上的一次性监听器（PKCE），绝不会经过聊天传输。
4. finish_login 会交换验证码，并将令牌保存到 ~/.config/mcp-google-docs/credentials.json（权限模式 0600）。

每次调用时都会重新读取令牌，因此连接会立即生效——无需重启 AI 应用。auth_status 会显示连接状态，logout 会撤销并删除令牌。

环境变量（CI、无人值守安装）

1. 创建或选择一个 Google Cloud 项目，并启用 Google Docs API 和 Google Drive API（导出、Markdown 转换和评论通过 Drive 端点处理）。

2. 配置 OAuth 同意屏幕，并创建 Desktop app OAuth 客户端。

3. 授权拥有文档或有权编辑文档的 Google 账号。启用 Use your own OAuth credentials 后，可通过 OAuth 2.0 Playground 获取刷新令牌。

4. 请求以下两个作用域：

   https://www.googleapis.com/auth/documents
   https://www.googleapis.com/auth/drive
   

   如果导出、Markdown 和评论只涉及通过此 OAuth 客户端创建的文档，那么更精简的配置只需 drive.file；只读工具则只需只读作用域组合 documents.readonly + drive.readonly。

测试模式下的 OAuth 刷新令牌可能会在 7 天后过期。若需要长期访问，请发布 OAuth 应用，或在 Workspace 网域中使用 Internal 应用。请将客户端密钥和刷新令牌视同密码妥善保管。

配置

所有变量均为可选项——不设置任何变量时，服务会从聊天中连接。

* 请提供 OAuth 三件套或访问令牌。

数据、限制与后台工作

• 请求会发送到 Google。 本地服务会刷新 Google OAuth 令牌并调用 Docs API；导出、Markdown 转换和评论在内部使用 Drive API 端点。匿名遥测数据包含安装 ID、软件包版本、AI 客户端和平台版本，以及工具名称——绝不包含 OAuth 令牌、文档内容、工具参数或提示词。设置 ASKADS_TELEMETRY=0 可选择退出。
• Google 会实施每分钟配额限制。 遇到 429 时，服务会退避后重试；读取操作在网络错误和 5xx 错误后也会重试，而写入操作在失败状态不确定时绝不会重放——重放写入可能会重复修改。
• 服务不会在后台轮询。 只有在被调用时，服务才会运行。如果你的 AI 应用支持计划任务，可以定期检查文档或其评论。

技术文档

• MCP 功能目录 — 每项工具的任务导向页面。
• 所有工具和输入
• 开发文档
• 发布文档
• Google Docs API 参考

支持

发现 Bug 或有使用场景需求？创建 issue 或在 Telegram 联系我们。

你已经读到最后了！