Google Workspace MCP 服务器

此模型上下文协议 (MCP) 服务器让您掌控您的 Google Workspace。连接您的帐户后 - 一个简单、安全的过程，只需一分钟 - 您就可以开始使用了。在后台，它会保持您的连接安全和活动状态，因此您可以专注于完成工作，而不是管理登录和权限。

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

您的日历成为日常工作中值得信赖的盟友。不再有重复预订的会议或时区混淆。计划团队同步？它会找到完美的时间段。运行重复的研讨会？设置一次，就完成了。即使计划发生变化，也能快速轻松地找到适合每个人的新时间。无休止的“你什么时候有空？”电子邮件的日子已经结束。

将 Google Drive 从文件转储变成您的数字指挥中心。每个文档都找到它的位置，每个文件夹都讲述一个故事。与完全正确的人共享文件 - 不再有“谁可以编辑这个？”的困惑。正在寻找上周会议的演示文稿？不仅可以搜索名称，还可以搜索文件中的内容。无论您是组织一个小项目还是管理大量文档，一切都井井有条，就在您需要的地方。

TL;DR 设置

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

1. 创建 Google Cloud 项目：

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

2. 添加到 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 桌面)

3. 重启 Cline/Claude

4. 只需让 AI 助手“添加我的 Google 帐户” - 它将以对话方式引导您完成身份验证过程。

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

先决条件

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

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

MCP 服务器需要：

1. 上述步骤中的 Google OAuth 客户端 ID 和密钥
2. 用于存储配置的本地目录路径（推荐：~/.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/        # 从 Drive 下载的文件
│   └── uploads/         # 准备上传的文件
├── [email_2@domain.com]/
│   ├── downloads/
│   └── uploads/
└── shared/
    └── temp/           # 临时文件（自动清理）

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

服务器将自动：

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

开发构建

对于本地开发，您可以构建和运行容器：

# 构建镜像
docker build -t google-workspace-mcp:local .

# 使用所需的环境变量运行
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)

  • 添加和验证 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)

  • 创建和管理标签过滤器
  • 复杂的过滤条件：
    • 发件人/收件人模式
    • 主题/内容匹配
    • 附件存在
    • 消息大小规则
  • 自动化操作：
    • 标签应用
    • 重要性标记
    • 读取状态
    • 存档

Calendar 操作

事件管理

• 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)

  • 删除日历事件
  • 参加者的通知选项

Drive 操作

文件管理

• 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)

  • 删除文件和文件夹
  • 从 Drive 中完全删除

文件夹操作

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

权限

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

有关详细用法，请参阅 API 文档。

即将推出

未来服务

• Admin SDK 支持
• 其他 Google 服务

测试策略

单元测试方法

1. 简化的模拟

   • 使用静态模拟响应进行可预测的测试
   • 避免单元测试中复杂的端到端模拟
   • 专注于一次测试一个功能
   • 使用简单的实现来模拟外部依赖项（OAuth、文件系统）

2. 测试组织

   • 按功能对测试进行分组（例如，帐户操作、文件操作）
   • 使用清晰、描述性的测试名称
   • 保持测试的重点和隔离
   • 在测试之间重置模拟和模块

3. 模拟管理

   • 使用 jest.resetModules() 确保干净的状态
   • 在模拟更改后重新 require 模块
   • 显式跟踪模拟函数调用
   • 验证函数调用和结果

4. 文件系统测试

   • 使用简单的 JSON 结构
   • 专注于数据正确性而不是格式
   • 测试错误场景（缺少文件、无效的 JSON）
   • 验证文件操作，无需实现细节

5. 令牌处理

   • 使用静态响应模拟令牌验证
   • 分别测试成功和失败场景
   • 验证令牌操作，无需 OAuth 复杂性
   • 专注于帐户管理器的令牌处理逻辑

运行测试

# 运行所有测试
npm test

# 运行特定的测试文件
npm test path/to/test.ts

# 运行带有覆盖率的测试
npm test -- --coverage

# CI 构建运行所有测试并生成覆盖率报告
npm run test:ci

最佳实践

1. 身份验证

   • 将凭据安全地存储在 MCP 设置中
   • 使用最少的必需范围
   • 正确处理令牌刷新

2. 错误处理

   • 检查响应状态
   • 适当处理身份验证错误
   • 实施适当的重试

3. 配置和安全

   • 每个用户维护自己的 Google Cloud 项目
   • 在 MCP 设置中配置 OAuth 凭据
   • 将令牌安全地存储在 ~/.mcp/google-workspace-mcp 中
   • 定期令牌轮换
   • 永远不要将敏感文件提交到 git
   • 为配置目录使用适当的文件权限

4. 本地开发设置

   • 在 MCP 设置中配置 OAuth 凭据
   • 创建 ~/.mcp/google-workspace-mcp 目录
   • 将敏感令牌保留在版本控制之外
   • 为每个帐户运行身份验证脚本

故障排除

常见设置问题

1. 缺少配置

   • 错误：“需要 GOOGLE_CLIENT_ID 环境变量”
   • 解决方案：在您的 MCP 设置文件中配置 OAuth 凭据（有关详细信息，请参阅 docs/API.md）

2. 身份验证错误

   • 错误：“无效的 OAuth 凭据”
   • 解决方案：
     • 验证您的 Google Cloud 项目是否已正确配置
     • 确保您已将自己添加为 OAuth 同意屏幕中的测试用户
     • 检查是否已启用 Gmail API 和 Google Calendar API
     • 验证 MCP 设置中的凭据是否与您的 OAuth 客户端配置匹配

3. 令牌问题

   • 错误：“令牌刷新失败”
   • 解决方案：使用 remove_workspace_account 删除帐户并重新进行身份验证
   • 检查您的 Google Cloud 项目是否已启用必要的 API 范围

4. 目录结构

   • 错误：“找不到目录”
   • 解决方案：确保 ~/.mcp/google-workspace-mcp 存在并具有适当的权限
   • 验证 Docker 是否有权挂载配置目录

有关更多帮助，请参阅 错误处理 文档。

许可证

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