Google Docs, 工作表, 驱动器, Gmail & Calendar MCP 服务器

连接 Claude 桌面、 Cursor 或 MCP 客户端到您的 Google Docs、 Google 工作表、 Google 驱动器、 Gmail 和 Google 日历 .

快速启动

1. 创建谷歌云 OAuth 客户端

1. 转到 谷歌云控台
2. 创建或选择一个工程
3. 启用 谷歌文档 API, (中文(简体) ), 谷歌工作表 API, (中文(简体) ), 谷歌驱动 API, (中文(简体) ), Gmail API 邮件,以及 谷歌日历 API
4. 配置 OAuth 同意屏幕 (外部,将您的电子邮件作为测试用户添加,并添加 gmail.modify 财务报告和审定财务报表 calendar.events 与 Docs/Sheets/Drive 瞄准镜平行的瞄准镜)
5. 创建一个 OAuth 客户端标识 (Desktop app 类型)
6. 复制 客户身份 财务报告和审定财务报表 客户端机密 从确认屏幕

需要更多细节吗? 见 逐步指示 在本页底部.

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 客户端

Claude 桌面 / cursor / Windsurf : (简体中文)

{
  "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 Docs 、 工作表和 Drive 的工具 :

谷歌文档

评论

谷歌工作表

谷歌工作表

谷歌驱动器

邮件

谷歌日历

用法实例

谷歌文档

"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"

谷歌驱动器

"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"

邮件

"Show me my 20 most recent unread emails"
"Search Gmail for messages from [email protected] in the last 7 days"
"Read the full body of message ID 18c3f4a2b1d9"
"Send an email to [email protected] 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 [email protected] next Wednesday at 11am with a Google Meet link"

标记下的工作流量

服务器支持一个完整的回程标记下的工作流程 :

1. 向下读取文档 : readDocument 与 format='markdown'
2. 编辑本地标记
3. 将更改推回 : replaceDocumentWithMarkdown

所支持的:标题,粗体,斜体,出击通路,链接,弹出/数字列表,水平规则.

Live Docs 验证

存储器包括用于 cloneTable 对抗真正的Google Docs 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 Docs, 验证 cloneTable,然后删除测试文件.

远程部署

在Google Cloud Run(或任何容器主机)上集中部署服务器,这样你的团队就可以不用本地安装即可使用. 服务器使用 MCP OAuth 2.1 导弹发射系统 fastMCP的内置程序 GoogleProvider -- MCP客户端自动处理认证流.

访问服务器根 URL(/),用于设置指令和即时复制客户端配置.

环境变量

设置

1. 创建 GCP 项目并启用 Docs, 工作表和驱动 API
2. 创建 OAuth 客户端( O)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 在部署和寒冷开始时使用持续授权
• 在无服务器平台( Cloud Run等) 上设定 MCP_STATELESS=true ——MCP会话在记忆中进行,因此规模到零擦去. 无国籍模式完全禁用会话跟踪; 每个请求通过 JWT/Firestore 令牌流独立认证
• ALLOWED_DOMAINS 限制访问特定的 Google 工作空间域
• 访问令牌自动刷新;不活动会话在30天后到期
• 用户可在任何时候通过 谷歌账户权限

更新您的部署

合并更改为 main 已经 没有 自动更新您的 Cloud 运行服务 。 每次部署都是独立的——在需要新功能或修正时需要手动重新部署.

更新:

1. 调取最新的代码 :

   git pull origin main
   

2. 调出至云跑:

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

   您现有的环境变量被保存着—— 无需通过 --set-env-vars 再来一次.

何时重新部署 :

• 错误修正和安全补丁 ——尽快重新部署
• 新特点 - 方便的时候重新部署
• 中断更改 ——在调用前检查释放注释

您可以对照最近发布的 页 次。 。 。 .

认证选项

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": "[email protected]"
      }
    }
  }
}

托肯存储

OAuth 刷新令牌存储于 ~/.config/google-docs-mcp/token.json (对) XDG_CONFIG_HOME) (中文(简体) ). OAuth客户端的ID和客户端的机密不存储在令牌文件中. 要重新授权,运行 auth 命令或删除符号文件.

多个谷歌账户

设定 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的限制.
• 工作表注释锁定 : API所创建的电子表格注释可以存储主锚元数据,但Google Workspace编辑器将Drive API主锚视为无选择的评论. 使用 createSheetsComment 与 includeCellLink=true 用于点击目标单元格的链接,或 createSheetsCellNote 当审查文本必须附于单元格本身时.
• 评论决议: 在Google Docs UI中,确定的地位可能不会持续.
• 已转换的文档 : 从 Word 转换的文档可能不支持所有 API 操作 .
• 标记下图像 : 尚未支持在减记到Docs转换中 .
• 嵌入式列表 : 有3+筑巢水平的列表可能具有格式化的突起.
• Gmail 硬删除 : trashMessage 将信件移动到回收站( 可逆的) 。 永久删除要求范围更广 https://mail.google.com/ 范围,而不在v0.1中暴露.
• Gmail 附件 : getMessage 返回附件元数据,但尚未下载附件字节.
• Gmail HTML 电子邮件发送 : sendEmail 只发送纯文本。 对于 HTML 机构,将 HTML 粘入 body 页:1.
• 日历范围 : calendar.events 允许活动 CRUD 在已有日历中创建或删除整个日历.
• 日历经常性活动: updateEvent 财务报告和审定财务报表 deleteEvent 修改整个反复出现的序列,除非您瞄准返回的特定实例ID listEvents 与 singleEvents=true。 。 。 .

解决问题

• 服务器不会启动 :
  • 校验 GOOGLE_CLIENT_ID 财务报告和审定财务报表 GOOGLE_CLIENT_SECRET 设置在 env 块.
  • 尝试手动运行 : npx @a-bonus/google-docs-mcp 并检查 stderr 的错误.
• 授权错误 :
  • 确保 Docs, Sheets, Drive, Gmail, 和日历 API 在 Google Cloud Console 中启用.
  • 确认您的电子邮件被列为 OAuth 同意屏幕上的测试用户,并且所有所需的范围(Docs, Sheets, Drive, gmail.modify, (中文(简体) ), calendar.events)被添加到同意屏幕中.
  • 重新授权 : npx @a-bonus/google-docs-mcp auth
  • 删除 ~/.config/google-docs-mcp/token.json 并重新授权如果升级——Gmail和日历范围在后期版本中被添加,所以现有的符号必须被刷新.
  • 远程(Cloud Run)用户必须从他们的MCP客户端签名并重新签名,因此Google重新发布对新范围列表的同意.
• 标签出错 :
  • 使用 listTabs 以查看可用的标签标识.
  • 奥米 tabId 用于单调文档.
• OAuth签入时在claude.ai上发现了"Page not found"(远程部署):
  • 症状:点击自定义的MCP连接器Connect登陆克洛德"Page找不到"一页,取而代之的是Google的签入屏幕.
  • 原因:云跑冷起. 在容器完成旋转前,第一个请求是闲置的服务时间,克劳德将失败的重定向到它的404页.
  • 工作周期:难于更新页面Cmd+Shift+R 在macOS上, Ctrl+Shift+R 在Windows/Linux上). 第二个请求涉及一个现在很温暖的例子,OAuth流量通常会得到收益.
  • 永久固定:设置 --min-instances=1 在您的"云跑"服务中,保持一个实例总是温暖(gcloud run services update <service> --region <region> --min-instances=1保留记忆的费用为每月2至3美元.
• 在重新部署(远程部署)后意外地重新校正:
  • 原因 : JWT_SIGNING_KEY 是在每一个容器启动时自动生成的,因此将所有先前发布的会话都无效.
  • 修补:设置马厩 JWT_SIGNING_KEY env var on the Cloud Run service 这样它就能活下来重启: gcloud run services update <service> --region <region> --update-env-vars JWT_SIGNING_KEY=$(openssl rand -hex 32). 这一变化之后定出的会话将在未来重新部署中存活下来.
• 有多个 MCP 会话的高 CPU : 有些客户打电话来 tools/list 经常这样 FastMCP在其它情况下会在每个请求上为每个工具重算出JSON Schema,每个进程可以给一个CPU核心打针. 此服务器在 stdio 启动和替换前预先计算出有效载荷一次 tools/list 拥有缓存快照的处理器 。 如果仍然看到持续负载,请用 sample <pid> 1 10 (macOS) 或 (中文(简体) ) node --cpu-prof 并报之.

谷歌云设置细节

捐款

欢迎捐款! 见 捐款额 结构概况和准则.

许可证

麻省理工学院 -- -- 见 自由主义 详细情况.