Google Workspace MCP 工具

@aaronsb/google-workspace-mcp

0 Stars 402 次浏览 aaronsb 更新于 2026-08-23

提供经过身份验证的访问Google Workspace API的功能，重点是Gmail操作，并计划支持日历功能，具备安全的OAuth认证和多账户管理以及详细的错误处理。

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "google-workspace-mcp": {
      "args": [
        "run",
        "--rm",
        "-i",
        "-p",
        "8080:8080",
        "-v",
        "~/.mcp/google-workspace-mcp:/app/config",
        "-v",
        "~/Documents/workspace-mcp-files:/app/workspace",
        "-e",
        "GOOGLE_CLIENT_ID",
        "-e",
        "GOOGLE_CLIENT_SECRET",
        "-e",
        "LOG_MODE=strict",
        "ghcr.io/aaronsb/google-workspace-mcp:latest"
      ],
      "command": "docker",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

该服务需要配置环境变量：GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REDIRECT_URI、GOOGLE_SCOPES

服务介绍

Google Workspace MCP 服务器

Robot Assistant

此模型上下文协议（MCP）服务器使您能够掌控您的 Google Workspace。一旦您连接了您的账户——这是一个简单且安全的过程，只需一分钟即可完成——您就可以开始使用了。在幕后，它会保持您的连接安全和活跃，因此您可以专注于完成工作，而无需管理登录和权限。

以您从未想过的方式掌控您的 Gmail 收件箱。想要上个季度的提案？几秒钟内就能找到。被新闻通讯淹没了吗？它们将自动分类到文件夹中。需要跟踪对重要邮件线程的回复？标签和过滤器为您完成这项工作。从起草完美的电子邮件到与团队进行对话管理，一切都会自然而然地就位。通过简化的附件处理，您可以轻松找到并管理电子邮件附件，而系统则会在幕后处理所有复杂的元数据。

您的日历将成为日常事务中的得力助手。不再有会议时间冲突或时区混淆的问题。计划一次团队同步会议？它会发现最佳的时间段。运行一个定期研讨会？设置一次，然后就完成了。即使计划发生变化，也能快速无痛地找到适合每个人的新时间。那些无休止的“你什么时候有空？”的邮件时代已经结束了。

将 Google Drive 从一个文件存储库转变为您的数字指挥中心。每份文档都有其位置，每个文件夹都讲述一个故事。与恰好合适的人共享文件——不再有“谁可以编辑这个？”的困惑。寻找上周会议的演示文稿？不仅搜索名称，还可以搜索文件内容。无论您是在组织一个小项目还是管理大量的文档，一切都将保持在您需要的地方。

TL;DR 设置

注意：对于像 Cline 这样的 AI 助手，请参阅 llms-install.md 获取专门的安装指南。

创建 Google Cloud 项目：

# 前往 Google Cloud Console
https://console.cloud.google.com
→ 创建项目
→ 启用 Gmail API 和 Calendar API
→ 配置 OAuth 同意屏幕（外部）
→ 创建 OAuth 桌面客户端 ID 和密钥

添加到 Cline 设置（例如，~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/home/aaron/.mcp/google-workspace-mcp:/app/config",
        "-v", "/home/aaron/Documents/workspace-mcp-files:/app/workspace",
        "-e", "GOOGLE_CLIENT_ID",
        "-e", "GOOGLE_CLIENT_SECRET",
        "-e", "LOG_MODE=strict",
        "ghcr.io/aaronsb/google-workspace-mcp:latest"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "123456789012-abcdef3gh1jklmn2pqrs4uvw5xyz6789.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-abcdefghijklmnopqrstuvwxyz1234"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}

日志模式：

normal（默认）：对每个日志级别使用适当的控制台方法
strict：将所有非 JSON-RPC 消息路由到 stderr（推荐用于 Claude 桌面版）

重启 Cline/Claude
只需让 AI “添加我的 Google 账户”——它会通过对话引导你完成身份验证过程。

有关更多信息，请参阅详细的设置指南。

前提条件

在使用此 MCP 服务器之前，您必须设置自己的 Google Cloud 项目，并启用 Google Workspace API：

在 Google Cloud Console 中创建一个新项目
启用所需的 API：
- Gmail API
- Google Calendar API
- Google Drive API
配置 OAuth 同意屏幕：
- 设置为“外部”
- 将自己添加为测试用户
- 添加 Gmail、Calendar 和 Drive 所需的范围
创建 OAuth 2.0 凭据：
- 选择“桌面应用程序”类型
- 记录您的客户端 ID 和客户端密钥
- 使用“urn:ietf:wg:oauth:2.0:oob”作为重定向 URI（这启用了带外认证）

MCP 服务器需要：

上述步骤中的 Google OAuth 客户端 ID 和密钥
存储配置的本地目录路径（推荐：~/.mcp/google-workspace-mcp）

注意：此服务器使用带外 (OOB) 认证流程，这意味着在每个账户的初始设置过程中，您需要手动复制粘贴授权码。

与 Cline 一起使用

将以下配置添加到您的 Cline MCP 设置中：

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/home/aaron/.mcp/google-workspace-mcp:/app/config",
        "-e", "GOOGLE_CLIENT_ID",
        "-e", "GOOGLE_CLIENT_SECRET",
        "-e", "LOG_MODE=strict",
        "ghcr.io/aaronsb/google-workspace-mcp:latest"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "123456789012-abcdef3gh1jklmn2pqrs4uvw5xyz6789.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "GOCSPX-abcdefghijklmnopqrstuvwxyz1234"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}

文件管理

服务器自动以结构化方式管理文件：

~/Documents/workspace-mcp-files/
├── [email_1@domain.com]/
│   ├── downloads/        # Files downloaded from Drive
│   └── uploads/         # Files staged for upload
├── [email_2@domain.com]/
│   ├── downloads/
│   └── uploads/
└── shared/
    └── temp/           # Temporary files (cleaned up automatically)

WorkspaceManager 自动创建并维护此结构：

根据需要在文件下载/上传时创建目录
按用户邮箱组织文件
处理临时文件清理
维护适当的权限

你可以通过设置 WORKSPACE_BASE_PATH 环境变量来自定义工作区位置。

手动使用

重要：服务器需要在挂载的配置目录中有一个 accounts.json 文件。首次设置时，请在启动容器之前将 accounts.example.json 复制到你的配置目录中的 accounts.json。

你可以直接运行容器：

docker run -i --rm \
  -v ~/.mcp/google-workspace-mcp:/app/config \
  -v ~/Documents/workspace-mcp-files:/app/workspace \
  -e GOOGLE_CLIENT_ID=123456789012-abcdef3gh1jklmn2pqrs4uvw5xyz6789.apps.googleusercontent.com \
  -e GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz1234 \
  -e LOG_MODE=strict \
  ghcr.io/aaronsb/google-workspace-mcp:latest

服务器将自动：

创建和管理所有必要的配置文件
安全存储凭据和令牌
维护适当的文件权限

开发构建

本地构建脚本

为了快速进行类似 CI 的本地构建和 Docker 镜像创建，可以使用提供的脚本：

# Run the local build pipeline (installs, lints, tests, builds, and creates Docker image)
./scripts/build-local.sh

默认情况下，镜像被打上 google-workspace-mcp:local 标签。
若要使用详细输出（将所有日志打印到控制台），请添加 --verbose：
```
./scripts/build-local.sh --verbose
```

若要更改 Docker 镜像标签：

./scripts/build-local.sh --tag my-custom-tag

日志文件写入 /tmp/google-workspace-mcp/ 以便审查。

构建脚本使用了 Dockerfile.local，该文件针对本地开发进行了优化，不包含特定于平台的设置或 BuildKit 功能。这确保了在不同开发环境中的兼容性。

手动 Docker 构建

你也可以手动构建和运行容器：

# Build the image using the standard Dockerfile
docker build -t google-workspace-mcp:local .

# Or build using the local development Dockerfile (recommended for local development)
docker build -t google-workspace-mcp:local -f Dockerfile.local .

# Run with required environment variables
docker run -i --rm \
  -v ~/.mcp/google-workspace-mcp:/app/config \
  -v ~/Documents/workspace-mcp-files:/app/workspace \
  -e GOOGLE_CLIENT_ID=123456789012-abcdef3gh1jklmn2pqrs4uvw5xyz6789.apps.googleusercontent.com \
  -e GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz1234 \
  -e LOG_MODE=strict \
  google-workspace-mcp:local

特性

简化的附件处理，带有自动元数据管理
专注于关键信息的简化电子邮件回复
强大的附件索引和检索系统
跨 Gmail 和 Calendar 的高效文件管理
自动清理过期附件

可用工具

帐户管理

list_workspace_accounts（别名：list_accounts, get_accounts, show_accounts）
- 列出所有已配置的 Google 帐户及其认证状态
- 在执行其他操作之前必须首先调用
- 验证所需的 API 范围
- 支持多个帐户选择
authenticate_workspace_account（别名：auth_account, add_account, connect_account）
- 添加并认证用于 API 访问的 Google 帐户
- 支持帐户分类（工作、个人）
- 处理带用户交互的 OAuth 流程
- 自动管理令牌刷新
remove_workspace_account（别名：delete_account, disconnect_account, remove_account）
- 移除 Google 帐户及其关联令牌
- 清理存储的凭证

Gmail 操作

消息和搜索

search_workspace_emails (别名: search_emails, find_emails, query_emails)
- 高级邮件过滤功能：
  - 发件人/收件人过滤
  - 主题和内容搜索
  - 日期范围过滤
  - 附件存在性
  - 基于标签的过滤
  - 复杂的 Gmail 查询语法支持
- 常见搜索模式：
  - 会议邮件
  - 人力资源/行政通信
  - 团队更新
  - 新闻简报
send_workspace_email (别名: send_email, send_mail, create_email)
- 发送带有完整格式的邮件
- 支持 CC/BCC 收件人
- 附件处理
- 邮件线程支持

设置与配置

get_workspace_gmail_settings (别名: get_gmail_settings, gmail_settings, get_mail_settings)
- 访问帐户设置
- 语言偏好
- 签名配置
- 自动回复状态
- 过滤器和转发规则

草稿管理

manage_workspace_draft (别名: manage_draft, draft_operation, handle_draft)
- 完整的草稿 CRUD 操作：
  - 创建新草稿
  - 查看现有草稿
  - 更新草稿内容
  - 删除草稿
  - 发送草稿
- 支持：
  - 新邮件草稿
  - 带有线程的回复草稿
  - 草稿修改
  - 草稿发送

标签管理

manage_workspace_label (别名: manage_label, label_operation, handle_label)
- 完整的标签 CRUD 操作
- 支持嵌套标签
- 自定义颜色配置
- 可见性设置
manage_workspace_label_assignment (别名: assign_label, modify_message_labels, change_message_labels)
- 对邮件应用或移除标签
- 批量标签修改
- 系统标签更新
manage_workspace_label_filter (别名: manage_filter, handle_filter, filter_operation)
- 创建和管理标签过滤器
- 复杂的过滤条件：
  - 发件人/收件人模式
  - 主题/内容匹配
  - 附件存在性
  - 邮件大小规则
- 自动操作：
  - 应用标签
  - 重要性标记
  - 已读状态
  - 归档

日历操作

事件管理

list_workspace_calendar_events (别名: list_events, get_events, show_events)
- 列出日历事件并进行筛选
- 指定日期范围
- 事件内的文本搜索
- 可自定义的结果限制
get_workspace_calendar_event (别名: get_event, view_event, show_event)
- 详细的事件信息
- 参与者状态
- 事件设置
manage_workspace_calendar_event (别名: manage_event, update_event, respond_to_event)
- 事件响应管理：
  - 接受/拒绝邀请
  - 标记为待定
  - 提议新时间
  - 更新事件时间
- 支持评论
- 时区处理
create_workspace_calendar_event (别名: create_event, new_event, schedule_event)
- 创建新的日历事件
- 支持：
  - 单个事件
  - 循环事件（RRULE格式）
  - 多个参与者
  - 指定时区
  - 事件描述
  - 冲突检查
delete_workspace_calendar_event (别名: delete_event, remove_event, cancel_event)
- 删除日历事件
- 通知参与者的选项

驱动器操作

文件管理

list_drive_files (别名: list_files, get_files, show_files)
- 列出文件，并可选过滤
- 按文件夹过滤
- 自定义查询支持
- 排序和分页
- 字段选择
search_drive_files (别名: search_files, find_files, query_files)
- 全文搜索文件内容
- 按MIME类型过滤
- 按文件夹过滤
- 包括/排除已删除的文件
- 高级查询选项
upload_drive_file (别名: upload_file, create_file, add_file)
- 上传新文件
- 设置文件元数据
- 指定父文件夹
- 支持多种文件类型
download_drive_file (别名: download_file, get_file_content, fetch_file)
- 下载任意类型的文件
- 导出Google Workspace文件
- 格式转换选项
- 自动MIME类型处理
delete_drive_file (别名: delete_file, remove_file, trash_file)
- 删除文件和文件夹
- 从驱动器中彻底移除

文件夹操作

create_drive_folder (别名: create_folder, new_folder, add_folder)
- 创建新文件夹
- 支持嵌套文件夹
- 指定父文件夹
- 文件夹元数据

权限

update_drive_permissions (别名: share_file, update_sharing, modify_permissions)
- 更新共享设置
- 多种权限类型：
  - 用户权限
  - 组权限
  - 域共享
  - 公共访问
- 各种访问角色：
  - 所有者
  - 组织者
  - 文件组织者
  - 编写者
  - 评论者
  - 阅读者
- 公共文件的发现设置

请参阅API文档以获取详细用法。

即将推出

未来服务

Admin SDK支持
其他Google服务

测试策略

单元测试方法

简化模拟
- 使用静态模拟响应进行可预测的测试
- 避免在单元测试中使用复杂的端到端模拟
- 一次只测试一个功能点
- 用简单的实现来模拟外部依赖（如 OAuth、文件系统）
测试组织
- 按功能分组测试（例如，账户操作、文件操作）
- 使用清晰且具有描述性的测试名称
- 保持测试专注且隔离
- 在测试之间重置模拟和模块
模拟管理
- 使用 jest.resetModules() 确保干净的状态
- 在修改模拟后重新加载模块
- 显式跟踪模拟函数调用
- 验证函数调用和结果
文件系统测试
- 使用简单的 JSON 结构
- 专注于数据正确性而非格式
- 测试错误场景（如缺失文件、无效 JSON）
- 在不涉及实现细节的情况下验证文件操作
令牌处理
- 使用静态响应模拟令牌验证
- 分别测试成功和失败场景
- 在不考虑 OAuth 复杂性的情况下验证令牌操作
- 专注于账户管理器的令牌处理逻辑

运行测试

# Run all tests
npm test

# Run specific test file
npm test path/to/test.ts

# Run tests with coverage
npm test -- --coverage

# CI builds run all tests with coverage reporting
npm run test:ci

最佳实践

认证
- 在 MCP 设置中安全地存储凭证
- 使用最小必需的作用域
- 正确处理令牌刷新
错误处理
- 检查响应状态
- 适当处理认证错误
- 实现适当的重试机制
配置与安全
- 每个用户维护自己的 Google Cloud 项目
- 在 MCP 设置中配置 OAuth 凭证
- 将令牌安全地存储在 ~/.mcp/google-workspace-mcp 中
- 定期轮换令牌
- 不要将敏感文件提交到 git
- 对配置目录使用适当的文件权限
本地开发设置
- 在 MCP 设置中配置 OAuth 凭证
- 创建 ~/.mcp/google-workspace-mcp 目录
- 将敏感令牌排除在版本控制之外
- 为每个账户运行认证脚本

故障排除

常见设置问题

缺少配置
- 错误: "GOOGLE_CLIENT_ID 环境变量是必需的"
- 解决方案: 在您的 MCP 设置文件中配置 OAuth 凭据（详情请参阅 docs/API.md）
认证错误
- 错误: "无效的 OAuth 凭据"
- 解决方案:
  - 验证您的 Google Cloud 项目是否已正确配置
  - 确保您已在 OAuth 同意屏幕中将自己添加为测试用户
  - 检查 Gmail API 和 Google Calendar API 是否均已启用
  - 验证 MCP 设置中的凭据与您的 OAuth 客户端配置相匹配
令牌问题
- 错误: "令牌刷新失败"
- 解决方案: 使用 remove_workspace_account 移除账户并重新进行身份验证
- 检查您的 Google Cloud 项目是否启用了必要的 API 范围
目录结构
- 错误: "找不到目录"
- 解决方案: 确保 ~/.mcp/google-workspace-mcp 存在且具有适当的权限
- 验证 Docker 是否可以访问挂载的配置目录

如需更多帮助，请查阅错误处理文档。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

查看源码项目主页

MCP 服务配置

服务介绍

Google Workspace MCP 服务器

TL;DR 设置

前提条件

与 Cline 一起使用

文件管理

手动使用

开发构建

本地构建脚本

手动 Docker 构建

特性

可用工具

帐户管理

Gmail 操作

消息和搜索

设置与配置

草稿管理

标签管理

日历操作

事件管理

驱动器操作

文件管理

文件夹操作

权限

即将推出

未来服务

测试策略

单元测试方法

运行测试

最佳实践

故障排除

常见设置问题

许可证

相关 MCP 服务

开源版 与 企业版

企业版（含 FDE 交付）

技能定制开发服务

开源版与企业版