google-docs

Google Docs Workspace MCP 服务

一个为 AI 助手提供 Google Docs 集成功能的 MCP（Model Context Protocol）服务。支持个人 Google 账号（通过 OAuth2）和 Google Workspace 账号（通过启用全网域授权的服务账号）。

功能

• 读取文档：按文档 ID 或可分享的 URL 获取 Google Doc 的完整正文或仅获取标题大纲
• 创建文档：创建新的 Google Docs，并可选择添加初始内容
• 编辑文档：
  • 在文档末尾追加文本
  • 在指定索引处插入文本
  • 替换字符串的所有匹配项
  • 应用原始的 documents.batchUpdate 请求，实现全面的结构控制
• 删除文档：默认移至 Drive 垃圾桶，也可通过显式标志永久删除
• 导出文档：导出为 Markdown、HTML、纯文本、PDF、DOCX、ODT、RTF 或 EPUB
• 共享文档（受限）：向用户、群组、网域或任何持有链接的人授予读取、评论或写入权限
• 两种身份验证方式：个人账号使用 OAuth2，Google Workspace 使用服务账号
• 权限限制：通过 GOOGLE_DOCS_ENABLED_TOOLGROUPS 按群组限制工具

安装

npm install google-docs-workspace-mcp-server

或使用 npx 直接运行：

npx google-docs-workspace-mcp-server

身份验证

此服务支持两种身份验证模式。请选择适合你账号类型的方式。

选项 1：OAuth2（个人 Google 账号）

适用于个人 @gmail.com 账号，或没有 Workspace 管理员访问权限的任何 Google 账号。

前提条件

1. 前往 Google Cloud Console
2. 创建或选择一个项目
3. 启用 Google Docs API 和 Google Drive API
4. 配置 OAuth 同意屏幕：
   • 选择 External 用户类型
   • 将自己添加为测试用户
   • 发布应用（在同意屏幕上点击“Publish”），以防刷新令牌每 7 天过期。个人使用无需完成 Google 全面验证。
5. 创建 OAuth 2.0 凭据：
   • 选择 Desktop app 作为应用类型
   • 重要：发布应用后再创建新凭据
6. 复制 Client ID 和 Client Secret

获取刷新令牌

运行内置的设置命令：

npx google-docs-workspace-mcp-server oauth-setup <client_id> <client_secret>

也可以通过环境变量传入凭据：

GOOGLE_DOCS_OAUTH_CLIENT_ID=... GOOGLE_DOCS_OAUTH_CLIENT_SECRET=... npx google-docs-workspace-mcp-server oauth-setup

**端口冲突？**如果端口 3000 已被占用，请指定其他端口：

PORT=3001 npx google-docs-workspace-mcp-server oauth-setup <client_id> <client_secret>

桌面应用凭据会自动允许在任何端口使用 http://localhost 重定向，因此无需额外配置 Google Cloud Console。

这将打开浏览器供你登录 Google，并打印刷新令牌。只需执行一次此操作即可；只要 OAuth 同意屏幕已发布，刷新令牌就不会过期。

环境变量（OAuth2）

变量	必需	描述
GOOGLE_DOCS_OAUTH_CLIENT_ID	是	来自 Google Cloud Console 的 OAuth2 客户端 ID
GOOGLE_DOCS_OAUTH_CLIENT_SECRET	是	OAuth2 客户端密钥
GOOGLE_DOCS_OAUTH_REFRESH_TOKEN	是	来自设置脚本的刷新令牌
GOOGLE_DOCS_ENABLED_TOOLGROUPS	否	以逗号分隔的工具组列表（默认为全部）

Claude Desktop 配置（OAuth2）

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["google-docs-workspace-mcp-server"],
      "env": {
        "GOOGLE_DOCS_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_DOCS_OAUTH_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_DOCS_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

选项 2：服务账号（Google Workspace）

适用于可由网域管理员授予全网域授权的 Google Workspace 组织。

前提条件

1. 前往 Google Cloud Console
2. 创建或选择一个项目
3. 启用 Google Docs API 和 Google Drive API
4. 创建一个启用了全域委派的服务账号
5. 在 Google Workspace Admin Console 中，授予该服务账号以下范围的访问权限：
   • https://www.googleapis.com/auth/documents（读取和编辑文档）
   • https://www.googleapis.com/auth/drive（对被模拟用户的 Drive 拥有完整的读写权限——导出文档、读取评论以及管理任意现有文档时都需要此权限，包括此应用未创建的文件）
6. 下载 JSON 密钥文件

环境变量（服务账号）

变量	必需	说明
GOOGLE_DOCS_SERVICE_ACCOUNT_CLIENT_EMAIL	是	服务账号电子邮件地址
GOOGLE_DOCS_SERVICE_ACCOUNT_PRIVATE_KEY	是	服务账号私钥（PEM 格式）
GOOGLE_DOCS_IMPERSONATE_EMAIL	是	要模拟的电子邮件地址
GOOGLE_DOCS_ENABLED_TOOLGROUPS	否	要启用的工具组列表，以逗号分隔（默认：所有组）

你可以在服务账号 JSON 密钥文件中找到 client_email 和 private_key 的值。

Claude Desktop 配置（服务账号）

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["google-docs-workspace-mcp-server"],
      "env": {
        "GOOGLE_DOCS_SERVICE_ACCOUNT_CLIENT_EMAIL": "[email protected]",
        "GOOGLE_DOCS_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
        "GOOGLE_DOCS_IMPERSONATE_EMAIL": "[email protected]"
      }
    }
  }
}

注意： 对于私钥，你可以：

1. 直接使用密钥，并用 \n 表示换行符（如上所示）
2. 从能够保留换行符的 shell 设置环境变量

工具组

该服务支持三个工具组，用于基于权限的访问控制：

组	包含的工具	风险级别
readonly	get_document、get_document_outline、export_document、list_comments	低
readwrite	所有只读工具 + create_document、update_document、delete_document、append_text、insert_text、replace_text	中
readwrite_external	所有读写工具 + share_document	高

默认情况下，所有工具组均已启用。要限制访问，请设置 GOOGLE_DOCS_ENABLED_TOOLGROUPS 环境变量：

# Read-only access (no writes or sharing)
GOOGLE_DOCS_ENABLED_TOOLGROUPS=readonly

# Read and write, but no sharing
GOOGLE_DOCS_ENABLED_TOOLGROUPS=readwrite

# Full access including sharing (default)
GOOGLE_DOCS_ENABLED_TOOLGROUPS=readwrite_external

安全提示： share_document 工具位于单独的 readwrite_external 组中，因为它可以向组织外部的用户授予访问权限，其风险高于纯内部编辑。

可用工具

所有接受 document_id 的工具都支持原始 Google Docs ID（例如，1AbCdEf...）或可分享的 Docs URL（例如，https://docs.google.com/document/d/1AbCdEf.../edit）。服务会自动提取 ID。

get_document

获取 Google 文档，并返回其标题、大纲和完整正文。

参数：

• document_id（字符串，必需）：Google Docs ID 或 URL
• format（字符串，可选）：text（默认值），用于生成便于阅读的输出；或 json，用于返回原始的 documents.get API 资源

get_document_outline

仅返回文档的标题结构——无需获取完整正文，即可快速了解较长文档的内容。

参数：

• document_id（字符串，必需）：Google Docs ID 或 URL

create_document

创建新的 Google 文档。

参数：

• title（字符串，必填）：文档标题
• initial_content（字符串，可选）：插入新文档的纯文本

update_document

应用原始的 documents.batchUpdate 请求。对于其他更专用工具未涵盖的 Docs API 操作（例如，应用段落样式、插入表格、操作命名范围），可使用此备用方式。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• requests（数组，必填）：documents.batchUpdate 请求对象数组（API 参考）

示例：

{
  "document_id": "1AbCdEf...",
  "requests": [
    {
      "insertText": {
        "location": { "index": 1 },
        "text": "Hello, world!\n"
      }
    },
    {
      "updateParagraphStyle": {
        "range": { "startIndex": 1, "endIndex": 14 },
        "paragraphStyle": { "namedStyleType": "HEADING_1" },
        "fields": "namedStyleType"
      }
    }
  ]
}

append_text

在文档末尾追加文本。自动解析正文末尾的索引。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• text（字符串，必填）：要追加的文本

insert_text

在指定索引处插入文本。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• index（数字，必填）：插入索引（必须 ≥ 1）
• text（字符串，必填）：要插入的文本

replace_text

在整个文档中查找并替换文本。会报告替换的匹配项数量。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• find（字符串，必填）：要查找的字符串
• replace（字符串，必填）：替换字符串
• match_case（布尔值，可选）：匹配是否区分大小写（默认值：false）

delete_document

默认将文档移至云端硬盘垃圾箱，也可永久删除。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• permanent（布尔值，可选）：为 true 时永久删除，而不是移至垃圾箱（默认值：false）

export_document

以其他格式导出文档。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• format（字符串，必填）：可选值：markdown、html、txt、pdf、docx、odt、rtf、epub

文本格式（markdown、html、txt）会以内联形式返回。二进制格式（pdf、docx、odt、rtf、epub）会以 base64 编码形式返回。

list_comments

列出文档中的评论，包括串联回复和已解决状态。读取 Drive comments.list API，并提供每条评论的作者、时间戳、已解决/未解决状态、评论所引用的锚定文本、评论正文及所有回复（包括已解决或重新开启讨论串的回复）。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• include_resolved（布尔值，可选）：包含已解决（已关闭）的讨论串（默认值：true）。设为 false 时，仅显示未解决的评论。
• include_deleted（布尔值，可选）：包含已删除的评论（默认值：false）

读取此应用未创建的文档中的评论，需要 https://www.googleapis.com/auth/drive 范围（仅使用范围更窄的 drive.file 不足以完成此操作）。

share_document

向用户、群组、网域或任何拥有链接的人授予访问权限。此功能仅对 readwrite_external 组开放。

参数：

• document_id（字符串，必填）：Google Docs ID 或 URL
• type（字符串，必填）：可选值：user、group、domain、anyone
• role（字符串，必填）：可选值：reader、commenter、writer
• email_address（字符串，条件必填）：当 type=user 或 type=group 时必填
• domain（字符串，条件必填）：当 type=domain 时必填
• send_notification_email（布尔值，可选）：是否由 Google 发送电子邮件通知（默认值：true）

开发

设置

# Install dependencies
npm run install-all

# Build
npm run build

# Run in development mode
npm run dev

测试

本服务采用四层测试策略：

层级	命令	是否调用真实 API？	所需凭据
功能	npm test	否	无
集成	npm run test:integration	否	无
端到端	npm run test:e2e	是	OAuth2 或服务账号（已加密）
手动	npm run test:manual	是	OAuth2 或服务账号（你的 .env）

功能测试和集成测试会在每次提交时于 CI 中运行。端到端测试使用固定的测试文档和提交到代码仓库（已加密）的刷新令牌，针对 Google Docs 和 Drive 的线上 API 运行。

运行端到端测试

端到端测试位于 tests/e2e/，用于针对真实 Google API 测试完整的 MCP 服务。其中包括：

• 针对固定的现有测试文档进行只读断言
• 一个自动清理的生命周期测试，端到端地创建 → 修改 → 导出 → 分享 → 删除新文档
• 针对不存在的文档 ID 的错误处理检查

完整测试套件会针对每种认证模式各运行一次——配置好测试套件后，OAuth2（个人账号）和服务账号（Workspace 模拟）都会始终接受测试。这能在问题进入生产环境之前，发现特定于认证模式的错误（令牌刷新与 JWT 签名、模拟、SA 专用的 subject 声明）。测试套件会在凭据不完整时立即失败：只要设置了任何 OAuth 或 SA 环境变量，就必须设置所有必需变量，否则测试套件会在模块加载时抛出错误。唯一有效的“无凭据”状态是 fork PR，此时 MCP_SERVERS_MASTER_KEY 不可用，整个测试套件会跳过。

凭据以加密形式存储在 tests/e2e/.env.enc 中，并在运行时使用整个 mcp-servers/ 工作区共用的 MCP_SERVERS_MASTER_KEY 解密。

在本地运行端到端测试：

# 1. Decrypt the e2e credentials (one-time per checkout)
cd mcp-servers
MCP_SERVERS_MASTER_KEY="<key>" ./scripts/decrypt-credentials.sh google-docs

# 2. Run the suite (this also rebuilds the server and the test client)
cd servers/google-docs
npm run test:e2e

主密钥存储在 1Password 的“MCP Servers Master Key”条目中——如果你没有访问权限，请向有权限的队友索取。解密后的 .env 已加入 gitignore；只有 .env.enc 会提交。

如果缺少 tests/e2e/.env 或凭据无效，测试套件会平稳地跳过，而不会失败——因此，在无法获取主密钥的 fork 上，CI 不会因此中断。

有关固定测试文档、OAuth 范围、令牌轮换、SA 配置步骤以及所测试工具的完整列表，请参阅 tests/e2e/STATE.md。

更新端到端测试凭据

如果刷新令牌被撤销、过期或 OAuth 客户端发生变更，请生成新的刷新令牌并重新加密：

# 1. Mint a new refresh token via the OAuth flow (see tests/e2e/STATE.md for the full procedure)
# 2. Update tests/e2e/.env with the new GOOGLE_DOCS_OAUTH_REFRESH_TOKEN
# 3. Re-encrypt
cd mcp-servers
MCP_SERVERS_MASTER_KEY="<key>" ./scripts/encrypt-credentials.sh google-docs
# 4. Commit the updated .env.enc
git add servers/google-docs/tests/e2e/.env.enc

许可证

MIT