AI导哈

Google Workspace访问服务

提供对Google Drive、Docs、Sheets、Slides、Calendar、Gmail和Contacts的访问服务，支持文件管理、文档编辑、邮件处理和日程安排。

  • by dguido
  • TypeScript
  • 本地部署
  • 37 星标
  • 更新于
在 GitHub 查看 dguido/google-workspace-mcp

使用说明

谷歌工作区MCP服务器

MCP服务器为Claude提供访问Google云端硬盘、文档、表格、幻灯片、日历、Gmail和联系人的权限。

快速开始

1.设置谷歌云

  1. 去 谷歌云控制台 并创建或选择一个项目
  2. 启用所有必需的API （单击链接）
  3. 首选 API和服务>凭据 并创建OAuth 2.0客户端ID（桌面应用程序类型）
  4. 复制 客户端ID 和 客户端密钥

2.配置克劳德桌面

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_WORKSPACE_SERVICES": "drive,gmail,calendar"
      }
    }
  }
}

就是这样。在第一次工具调用时，会打开一个浏览器窗口，征求Google OAuth的同意。令牌会自动保存。

Alternative: file-based credentials

从Google Cloud Console下载JSON凭据并保存到 ~/.config/google-workspace-mcp/credentials.json，然后手动进行身份验证：

npx @dguido/google-workspace-mcp auth

看 高级配置 用于基于文件的设置、命名配置文件和多帐户设置。

你能做什么

Create a Google Doc called "Project Plan" in /Work/Projects with an outline for Q1.

Search for files containing "budget" and organize them into the Finance folder.

Create a presentation called "Product Roadmap" with slides for Q1 milestones.

谷歌云设置

1.创建谷歌云项目

  • 去 谷歌云控制台
  • 点击“选择项目”>“新建项目”
  • 命名您的项目（例如，“Google Drive MCP”）

2.启用所需的API

  • 一次启用所有API （单击链接）
  • 或者手动：转到“API和服务”>“库”并启用： Google Drive API, 谷歌文档API, 谷歌网页API, 谷歌幻灯片API, 谷歌日历API, Gmail API, 人民API

3.配置OAuth同意屏幕

  • 转到“API和服务”>“OAuth同意屏幕”
  • 填写应用程序名称、支持电子邮件和开发人员联系方式
  • 选择“外部”（或“内部”作为工作区）
  • 将您的电子邮件添加为测试用户
  • 添加作用域： drive.file, documents, spreadsheets, presentations, drive, drive.readonly, calendar, gmail.modify, gmail.labels, contacts

4.创建OAuth 2.0凭据

  • 转到“API和服务”>“凭据”
  • 点击“+创建证书”>“OAuth客户端ID”
  • 应用程序类型： 桌面应用程序
  • 复制 客户端ID 和 客户端密钥 （或下载JSON文件）

配置

文件位置

凭证和令牌都存储在 ~/.config/google-workspace-mcp/ 默认情况下：

文件 默认路径
OAuth凭据 ~/.config/google-workspace-mcp/credentials.json
身份验证令牌 ~/.config/google-workspace-mcp/tokens.json

环境变量

变量 描述
GOOGLE_CLIENT_ID OAuth客户端ID（最简单的设置——不需要凭据文件）
GOOGLE_CLIENT_SECRET OAuth客户端密钥（与 GOOGLE_CLIENT_ID)
GOOGLE_WORKSPACE_MCP_TOKEN_PATH 自定义令牌存储位置
GOOGLE_WORKSPACE_MCP_PROFILE 用于凭据隔离的命名配置文件
GOOGLE_WORKSPACE_SERVICES 要启用的以逗号分隔的服务列表

令牌高效输出（TOON）

对于将令牌使用率降低20-50%的LLM优化响应，启用TOON格式：

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_WORKSPACE_SERVICES": "drive,gmail,calendar",
        "GOOGLE_WORKSPACE_TOON_FORMAT": "true"
      }
    }
  }
}

TOON（面向令牌的对象表示法）通过消除重复的字段名，比JSON更紧凑地编码结构化响应。列表操作（日历、事件、电子邮件、过滤器）的节省最高。

服务配置

默认情况下，我们建议只启用核心服务(drive,gmail,calendar)如快速入门所示。这提供了文件管理、电子邮件和日历功能，而没有文档编辑工具的复杂性。

要启用其他服务，请将其添加到 GOOGLE_WORKSPACE_SERVICES:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["@dguido/google-workspace-mcp"],
      "env": {
        "GOOGLE_WORKSPACE_SERVICES": "drive,gmail,calendar,docs,sheets,slides"
      }
    }
  }
}

可用服务： drive, docs, sheets, slides, calendar, gmail, contacts

  • 省略 GOOGLE_WORKSPACE_SERVICES 完全启用所有服务
  • 统一工具(create_file, update_file, get_file_content)要求 drive, docs, sheets，以及 slides
  • 当您限制服务时，在身份验证期间只会请求这些服务的OAuth作用域。如果更改了已启用的服务，请重新进行身份验证以更新已授予的范围。

看 高级配置 用于命名配置文件、多帐户设置和环境变量。

可用工具

驱动器（29个工具）

search listFolder createFolder createTextFile updateTextFile deleteItem renameItem moveItem copyFile getFileMetadata exportFile shareFile getSharing removePermission listRevisions restoreRevision downloadFile uploadFile getStorageQuota starFile resolveFilePath batchDelete batchRestore batchMove batchShare listTrash restoreFromTrash emptyTrash getFolderTree

谷歌文档（8个工具）

createGoogleDoc updateGoogleDoc getGoogleDocContent appendToDoc insertTextInDoc deleteTextInDoc replaceTextInDoc formatGoogleDocRange

谷歌表格（7个工具）

createGoogleSheet updateGoogleSheet getGoogleSheetContent formatGoogleSheetCells mergeGoogleSheetCells addGoogleSheetConditionalFormat sheetTabs

谷歌幻灯片（10个工具）

createGoogleSlides updateGoogleSlides getGoogleSlidesContent formatSlidesText formatSlidesShape formatSlideBackground createGoogleSlidesTextBox createGoogleSlidesShape slidesSpeakerNotes listSlidePages

日历（7工具）

listCalendars listEvents getEvent createEvent updateEvent deleteEvent findFreeTime

Gmail（14个工具）

sendEmail draftEmail readEmail searchEmails deleteEmail modifyEmail downloadAttachment listLabels getOrCreateLabel updateLabel deleteLabel createFilter listFilters deleteFilter

联系人（6个工具）

listContacts getContact searchContacts createContact updateContact deleteContact

统一（3个工具）

createFile updateFile getFileContent

API完整参考

故障排除

“找不到OAuth凭据”

集 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET MCP配置中的env变量，或将凭据文件保存到 ~/.config/google-workspace-mcp/credentials.json.

“身份验证失败”或浏览器无法打开

确保凭据类型为“桌面应用程序”（而不是“Web应用程序”）。服务器使用操作系统分配的临时端口，因此不需要特定的端口可用。

“令牌过期”或“授予无效”

处于“测试”状态的应用程序在7天后令牌过期。重新验证：

rm ~/.config/google-workspace-mcp/tokens.json
npx @dguido/google-workspace-mcp auth

为了避免每周重新验证： 发布您的OAuth应用程序（请参阅 避免令牌过期 在......下面

“未启用API”

启用中缺少的API 谷歌云控制台 >API和服务>库。

即使使用有效令牌，也需要“登录”

取消应用程序访问权限 Google帐户权限，清除令牌，并重新进行身份验证。

完整故障排除指南

安全

  • 符合RFC 8252的OAuth 2.0，带有PKCE（代码交换证明密钥）
  • 仅环回身份验证服务器（127.0.0.1）
  • CSRF保护状态参数
  • 自动令牌刷新
  • 以0600权限存储的令牌
  • 所有处理都在本地进行
  • 切勿将凭据或令牌提交到版本控制

避免令牌过期

处于“测试”状态的OAuth应用程序会在7天后自动过期令牌。为了避免每周重新验证：

选项1：发布您的OAuth应用程序（推荐）

  1. 首选 谷歌云控制台 >API和服务>OAuth同意屏幕
  2. 点击“发布APP”
  3. 对于个人使用，您不需要完成谷歌的验证过程
  4. 已发布的应用程序在明确撤销之前保持令牌有效

注： 发布使您的应用程序可供任何Google用户使用，但由于您控制OAuth凭据，因此只有您可以进行身份验证。

选项2：使用内部应用程序（仅限工作区）

如果您有Google Workspace帐户：

  1. 在OAuth同意屏幕上将用户类型设置为“内部”
  2. 内部应用程序不会使令牌过期，也不需要发布

监控令牌年龄

使用 get_status 检查代币年龄。超过6天的令牌会自动显示警告。

发展

npm install
npm run build    # Compile TypeScript
npm run check    # typecheck + lint + format check
npm test         # Run tests

看 贡献指南 用于项目结构和开发工作流程。

起源

这个项目是对 piotr agier/谷歌驱动器mcp，最初由Piotr Agier创建。

许可证

MIT-有关详细信息，请参阅许可证文件。

相关 MCP