Google Docs MCP

谷歌文档、表格、驱动器、Gmail和日历MCP服务器

Demo Animation

将Claude Desktop、Cursor或任何MCP客户端连接到您的Google文档、Google表格、Google云端硬盘、Gmail和Google日历。

______________________________________________________________________

快速开始

1.创建Google Cloud OAuth客户端

1. 去 谷歌云控制台
2. 创建或选择项目
3. 启用 谷歌文档API, 谷歌网页API, Google Drive API, Gmail API，以及 谷歌日历API
4. 配置 OAuth同意屏幕 （外部，将您的电子邮件添加为测试用户，并添加 gmail.modify 和 calendar.events 文档/表格/驱动器范围旁边的范围）
5. 创建一个 OAuth客户端ID （桌面应用程序类型）
6. 复制 客户端ID 和 客户端密钥 从确认屏幕

需要更多细节吗？看 逐步说明 在本页底部。

2.授权

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y @a-bonus/google-docs-mcp auth

这将打开您的浏览器进行谷歌授权。批准后，刷新令牌将保存到 ~/.config/google-docs-mcp/token.json.

3.添加到您的MCP客户端

克劳德桌面/光标/风帆：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

当您的MCP客户端需要时，服务器会自动启动。

远程部署（云运行）

为您的团队部署一次，无需本地安装。服务器使用MCP OAuth 2.1，因此您的MCP客户端会自动处理身份验证。

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

然后，每个用户只需将URL添加到他们的MCP客户端即可——无npx、无令牌、无本地设置：

{
  "mcpServers": {
    "google-docs": {
      "type": "streamableHttp",
      "url": "https://your-service.run.app/mcp"
    }
  }
}

您的MCP客户端将在第一次连接时提示Google登录。看 远程部署 了解详情。

______________________________________________________________________

它能做什么？

跨Google文档、表格和驱动器的工具：

谷歌文件

评论

谷歌表格

谷歌表格

Google 云端硬盘

Gmail

谷歌日历

______________________________________________________________________

使用示例

谷歌文件

"Read document ABC123 as markdown"
"Append 'Meeting notes for today' to document ABC123"
"Make the text 'Important' bold and red in document ABC123"
"Replace the entire document with this markdown: # Title\n\nNew content here"
"Insert a 3x4 table at index 50 in document ABC123"

谷歌表格

"Read range A1:D10 from spreadsheet XYZ789"
"Write [[Name, Score], [Alice, 95], [Bob, 87]] to range A1 in spreadsheet XYZ789"
"Create a new spreadsheet titled 'Q1 Report'"
"Format row 1 as bold with a light blue background in spreadsheet XYZ789"
"Freeze the first row in spreadsheet XYZ789"
"Add a dropdown with options [Open, In Progress, Done] to range C2:C100"
"Create a table named 'Tasks' in range A1:D10 with columns: Task (TEXT), Status (DROPDOWN: 'Not Started','In Progress','Done'), Priority (NUMBER)"
"Add a medium solid border around A1:D10 in spreadsheet XYZ789"
"Protect the header row so collaborators can't accidentally edit it"
"Auto-fit row heights for rows 2–50 after wrapping text"

Google 云端硬盘

"List my 10 most recent Google Docs"
"Search for documents containing 'project proposal'"
"Create a folder called 'Meeting Notes' and move document ABC123 into it"

Gmail

"Show me my 20 most recent unread emails"
"Search Gmail for messages from alice@example.com in the last 7 days"
"Read the full body of message ID 18c3f4a2b1d9"
"Send an email to bob@example.com with the subject 'Weekly update' and this body..."
"Reply to message 18c3f4a2b1d9 with 'Thanks, confirmed.'"
"Star message 18c3f4a2b1d9 and archive it"
"Move message 18c3f4a2b1d9 to Trash"
"List all my Gmail labels"
"Draft a reply to that email but don't send it yet — let me review first"
"Show me my drafts, then send the one to bob@"
"Triage my unread inbox: tell me which 20 emails need attention and which are noise"

谷歌日历

"What's on my calendar this week?"
"Create an event titled 'Project review' tomorrow from 2pm to 3pm Pacific time"
"Quick add: lunch with Alex Friday 12:30"
"Reschedule event abc123 to next Monday at 10am"
"Delete the 'Standup' event tomorrow"
"List all events on my calendar between April 15 and April 22"
"Schedule a 30-minute meeting with bob@example.com next Wednesday at 11am with a Google Meet link"

Markdown工作流

服务器支持完整的往返降价工作流：

1. 以markdown方式阅读文档： readDocument 随着 format='markdown'
2. 在本地编辑标记
3. 将更改推回： replaceDocumentWithMarkdown

支持：标题、粗体、斜体、删除线、链接、项目符号/编号列表、水平规则。

实时文档验证

该存储库包括一个选择加入的实时集成测试 cloneTable 与真正的谷歌文档API相比。默认情况下会跳过它。

要求：

• 有效的 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET
• 已通过存储的授权令牌 npx -y @a-bonus/google-docs-mcp auth

运行它：

GOOGLE_DOCS_LIVE_TESTS=1 npm run test:live:docs

此测试创建临时源/目标Google文档，验证 cloneTable，然后删除测试文件。

______________________________________________________________________

远程部署

将服务器集中部署在Google Cloud Run（或任何容器主机）上，这样您的团队就可以在不进行本地安装的情况下使用它。服务器使用 MCP OAuth 2.1 内置FastMCP GoogleProvider --MCP客户端自动处理身份验证流。

访问服务器根URL(/)获取设置说明和可复制的客户端配置。

环境变量

设置

1. 创建GCP项目并启用文档、表格和驱动器API
2. 创建OAuth客户端(Web应用程序 类型，而非桌面）
3. 将授权重定向URI设置为 {BASE_URL}/oauth/callback
4. 部署到云运行：

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|ALLOWED_DOMAINS=yourdomain.com|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

注： 这 ^|^ 前缀更改了env-var分隔符 , 到 | 因为 ALLOWED_DOMAINS 包含逗号。

运作原理

• 默认情况下，OAuth会话存储在内存中，并在重新启动时丢失
• 对于生产，设置 TOKEN_STORE=firestore 和 JWT_SIGNING_KEY 用于跨部署和冷启动的持久身份验证
• ALLOWED_DOMAINS 限制对特定Google Workspace域的访问
• 访问令牌自动刷新；非活动会话将在30天后过期
• 用户可以随时通过以下方式撤销访问权限 Google帐户权限

更新部署

将更改合并到 main 做 不 自动更新您的Cloud Run服务。每个部署都是独立的——当你想要新功能或修复时，你需要手动重新部署。

要更新，请执行以下操作：

1. 提取最新代码：

   git pull origin main

1. 重新部署到云运行：

   gcloud run deploy your-service-name --source . --region your-region

您现有的环境变量将被保留，无需传递 --set-env-vars 再一次。

何时重新部署：

• Bug修复和安全补丁 --尽快重新部署
• 新功能 --在您方便的时候重新部署
• 重大变更 --重新部署前检查发行说明

您可以在 发布页面.

______________________________________________________________________

身份验证选项

OAuth（默认）

将您的Google Cloud OAuth客户端凭据作为环境变量传递：

服务帐户（企业）

对于具有域范围委派的Google Workspace：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json",
        "GOOGLE_IMPERSONATE_USER": "user@yourdomain.com"
      }
    }
  }
}

令牌存储

OAuth刷新令牌存储在 ~/.config/google-docs-mcp/token.json （尊重 XDG_CONFIG_HOME).OAuth客户端ID和客户端机密不存储在令牌文件中。要重新授权，请运行 auth 再次执行命令或删除令牌文件。

多个Google帐户

集 GOOGLE_MCP_PROFILE 将令牌存储在特定于配置文件的子目录中。这允许为不同的项目使用不同的Google帐户：

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_MCP_PROFILE": "work"
      }
    }
  }
}

令牌按配置文件存储：

~/.config/google-docs-mcp/
├── token.json              # default (no profile)
├── work/token.json         # GOOGLE_MCP_PROFILE=work
├── personal/token.json     # GOOGLE_MCP_PROFILE=personal

没有 GOOGLE_MCP_PROFILE，行为不变。

______________________________________________________________________

已知限制

• 评论锚定： 程序化创建的评论会出现在评论列表中，但不会明显地锚定在Google Docs UI中的文本上。这是Google Drive API的限制。
• 评论决议： 已解决状态可能不会在Google Docs UI中持续存在。
• 转换文件： 从Word转换的文档可能不支持所有API操作。
• Markdown表格/图片： 在markdown到Docs的转换中尚不支持。
• 深度嵌套列表： 具有3个以上嵌套级别的列表可能会有格式怪癖。
• Gmail硬删除： trashMessage 将邮件移动到废纸篓（可逆）。永久删除需要更广泛的 https://mail.google.com/ 在v0.1中没有公开。
• Gmail附件： getMessage 返回附件元数据，但尚未下载附件字节。
• Gmail HTML电子邮件发送： sendEmail 仅发送纯文本。对于HTML正文，将HTML粘贴到 body 字段——它将作为文本交付，而不是呈现。
• 日历范围： calendar.events 允许对现有日历进行事件CRUD，但不能创建或删除整个日历本身。
• 日历定期事件： updateEvent 和 deleteEvent 修改整个重复序列，除非您以返回的特定实例ID为目标 listEvents 随着 singleEvents=true.

故障排除

• 服务器无法启动：

- 验证 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 设置在 env MCP配置块。 - 尝试手动运行： npx @a-bonus/google-docs-mcp 并检查stderr是否有错误。

• 授权错误：

- 确保在Google Cloud Console中启用了文档、表格、驱动器、Gmail和日历API。 - 确认您的电子邮件在OAuth同意屏幕上被列为测试用户，并且所有必需的范围（文档、表格、驱动器、， gmail.modify, calendar.events)被添加到同意屏幕。 - 重新授权： npx @a-bonus/google-docs-mcp auth - 删除 ~/.config/google-docs-mcp/token.json 如果升级，则重新授权——Gmail和日历范围在以后的版本中添加，因此必须刷新现有的令牌。 - 远程（云运行）用户必须注销并从其MCP客户端重新登录，以便谷歌根据新的范围列表重新发出同意书。

• 选项卡错误：

- 使用 listTabs 查看可用的选项卡ID。 - 省略 tabId 对于单选项卡文档。

• OAuth登录期间claude.ai上的“找不到页面”（远程部署）：

- 症状：在自定义MCP连接器上单击“连接”会显示在Claude“找不到页面”页面上，而不是谷歌登录屏幕上。 - 原因：云跑冷启动。在容器完成旋转之前，对空闲服务的第一个请求超时，Claude将失败的重定向路由到其404页面。 - 解决方法：硬刷新页面(Cmd+Shift+R 在macOS上， Ctrl+Shift+R 在Windows/Linux上）。第二个请求碰到一个现在很热的实例，OAuth流程正常进行。 - 永久修复：设置 --min-instances=1 在您的Cloud Run服务上保持一个实例始终温暖(gcloud run services update --region --min-instances=1).内存预留费用约为每月2-3美元。

• 重新部署后意外重新验证（远程部署）：

- 原因： JWT_SIGNING_KEY 每次容器启动时都会自动生成，因此重新部署会使所有以前发出的会话无效。 - 修复：设置一个稳定 JWT_SIGNING_KEY Cloud Run服务上的env var，使其在重启后仍能存活： gcloud run services update --region --update-env-vars JWT_SIGNING_KEY=$(openssl rand -hex 32)。此更改后创建的会话将在未来重新部署后继续存在。

• 具有多个MCP会话的高CPU： 一些客户致电 tools/list 经常。否则，FastMCP会为每个请求上的每个工具重新计算JSON模式，这可以为每个进程固定一个CPU核心。此服务器在stdio启动之前预计算一次有效负载，并替换 tools/list 带有缓存快照的处理程序。如果你仍然看到持续的负载，用 `sample

1 10 （macOS）或 node --cpu-prof` 并报告。

______________________________________________________________________

谷歌云设置详细信息

Step-by-step Google Cloud Console instructions

对于 远程部署，创建类型为的OAuth客户端 Web应用程序 （不是桌面应用程序）。仅将桌面应用程序用于本地stdio使用。

1. 转到谷歌云控制台： 打开 console.cloud.google.com
2. 创建或选择项目： 点击项目下拉菜单>“新建项目”。命名它（例如“MCP文档服务器”），然后单击“创建”。
3. 启用API：

- 导航到“API和服务”>“库” - 搜索并启用： 谷歌文档API, 谷歌网页API, Google Drive API, Gmail API, 谷歌日历API

1. 配置OAuth同意屏幕：

- 转到“API和服务”>“OAuth同意屏幕” - 选择“外部”并单击“创建” - 填写：应用程序名称、用户支持电子邮件、开发人员联系电子邮件 - 点击“保存并继续” - 添加作用域： documents, spreadsheets, drive, gmail.modify, calendar.events - 点击“保存并继续” - 将您的Google电子邮件添加为测试用户 - 点击“保存并继续”

1. 创建凭据：

- 转到“API和服务”>“凭据” - 点击“+创建证书”>“OAuth客户端ID” - 应用程序类型：“桌面应用程序” - 点击“创建” - 复制 客户端ID 和 客户端密钥

______________________________________________________________________

贡献

欢迎投稿！看 贡献.md 用于开发设置、架构概述和指南。

许可证

麻省理工学院——见 许可证 了解详情。