Google Workspace MCP 服务器

这款模型上下文协议 (MCP) 服务器让您掌控自己的 Google Workspace。只需一分钟，即可轻松连接您的帐号，安全可靠。它会在后台确保您的连接安全且活跃，让您专注于完成工作，无需管理登录名和权限。

以您意想不到的方式掌控您的 Gmail 收件箱。想要上季度的提案？几秒钟内即可找到。新闻简报堆积如山？它们会自动分类归入文件夹。需要追踪重要主题的回复？标签和过滤器可为您完成所有工作。从撰写完美的电子邮件到管理与团队的对话，一切都轻而易举。借助简化的附件处理功能，您可以轻松查找和管理电子邮件附件，而系统会在后台处理所有复杂的元数据。

您的日历将成为您日常事务中值得信赖的助手。不再有重复预订的会议或时区混乱的情况。计划团队同步？它能帮您找到最合适的时间段。举办定期研讨会？只需设置一次，即可轻松搞定。即使计划有变，也能快速轻松地找到适合所有人的新时间。无休止地收到“您什么时候有空？”邮件的日子已经一去不复返了。

将 Google Drive 从文件转储变成您的数字指挥中心。每个文档都各归其位，每个文件夹都讲述着一个故事。与合适的人共享文件 - 不再需要“谁可以编辑这个文件？”的困惑。正在寻找上周会议的演示文稿？不仅搜索名称，还可以搜索文件内容。无论您是在组织小型项目还是管理海量文档，所有内容都能轻松找到。

TL;DR 设置

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

创建 Google Cloud 项目：
# Go to Google Cloud Console https://console.cloud.google.com → Create Project → Enable Gmail API and Calendar API → Configure OAuth consent screen (External) → Create OAuth Desktop Client ID and Secret
添加到 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 桌面）
重启克莱恩/克劳德
只需要求 AI“添加我的 Google 帐户” - 它就会以对话的方式指导您完成身份验证过程。

请参阅详细的设置指南以了解更多信息。

先决条件

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

在Google Cloud Console中创建新项目
启用所需的 API：
- Gmail API
- Google 日历 API
- Google Drive API
配置 OAuth 同意屏幕：
- 设置为“外部”
- 将自己添加为测试用户
- 添加 Gmail、日历和云端硬盘所需的范围
创建 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 和日历的高效文件管理
自动清理过期附件

可用工具

账户管理

list_workspace_accounts （别名：list_accounts、get_accounts、show_accounts）
- 列出所有已配置的 Google 帐户和身份验证状态
- 必须在其他操作之前先调用
- 验证所需的 API 范围
- 处理多个帐户选择
authenticate_workspace_account （别名：auth_account、add_account、connect_account）
- 添加并验证 Google 帐户以进行 API 访问
- 支持账户分类（工作、个人）
- 处理与用户交互的 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）
- 发送完整格式的电子邮件
- 支持抄送/密送收件人
- 附件处理
- 电子邮件线程支持

设置和配置

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 许可证 - 详情请参阅许可证文件

Google Workspace MCP Server

Integrations

Google Workspace MCP 服务器

TL;DR 设置

先决条件

与 Cline 一起使用

文件管理

手动使用

开发构建

本地构建脚本

手动 Docker 构建

特征

可用工具

账户管理

Gmail操作

消息和搜索

设置和配置

草稿管理

标签管理

日历操作

活动管理

驱动操作

文件管理

文件夹操作

权限

即将推出

未来服务

测试策略

单元测试方法

运行测试

最佳实践

故障排除

常见设置问题

执照

Related Resources

Appeared in Searches