gws-connector

GWS Connector

多账号 Google Workspace MCP 服务——通过智能路由连接多个 Gmail、Google Calendar 和 Google Drive 账号。

兼容 Claude Code、Gemini CLI、GitHub Copilot、Cursor、OpenAI Codex 以及任何兼容 MCP 的客户端。

为什么选择它

大多数 AI 编码助手只支持一个 Google 账号。如果你使用多个 Google 账号（个人和工作账号、多个客户的账号或不同组织的账号），就需要手动在账号之间切换。这个 MCP 服务可以让你一次性连接所有账号，并按标签、邮箱或域名路由请求。

功能

• 多账号 — 连接不限数量的 Gmail 和 Google Workspace 账号
• 智能路由 — 按标签（work）、邮箱或域名指定账号
• 每账号独立 OAuth — 不同组织可以使用各自的 GCP 凭据
• 安全存储 — 客户端密钥和令牌存储在操作系统密钥链中（在没有 GNOME Keyring 的 Linux 上回退到文件存储）
• 49 个工具 — Mail（11 个）、Calendar（7 个）、Drive（3 个）、Sheets（8 个）、Docs（4 个）、Contacts（2 个）、Tasks（5 个）、Slides（3 个）、账号管理（6 个）
• 账号管理 — 添加、移除、设置默认账号、列出账号
• 跨平台 — 标准 MCP 服务，可与任何兼容的客户端配合使用

对比

有不少优秀的 Google Workspace MCP 服务。当你需要多个账号和简化运维时，GWS Connector 是理想选择：

如果你始终只使用一个 Google 账号，并希望获得尽可能全面的工具覆盖（Forms、Chat、Vault 等），那么单账号服务（例如 taylorwilsdon/google_workspace_mcp ）可能更适合你。GWS Connector 专注于以清晰、安全的方式支持多账号 Gmail / Calendar / Drive / Sheets / Docs / Contacts / Tasks / Slides。

升级（Google Tasks）

Google Tasks 工具（gws.tasks.*）通过新增一个 OAuth scope （tasks）提供。现有用户必须为每个已连接账号重新授权，以便生成包含此 scope 的新令牌：

/gws:reauth

在批准浏览器中的授权页面之前，请查看新 scope 授予的权限——对账号的 Google Tasks 列表和任务拥有完整的读写权限。详情请参阅下方的scope 说明表。

重新授权之前，还必须在 GCP 项目的 OAuth 授权页面配置中添加 tasks scope 并启用 Tasks API，否则授权页面会拒绝该请求。在账号重新授权之前，gws.tasks.* 工具会返回权限不足错误，并指出需要运行的重新授权工具。

升级——联系人 / People API

Contacts 工具（gws.contacts.search、gws.contacts.directory_search）新增了两个只读 OAuth 范围（contacts.readonly、directory.readonly）。 现有用户必须为每个已连接的账号重新授权，以便生成包含这些范围的新令牌：

/gws:reauth

在浏览器中批准授权页面之前，请查看新增范围授予的权限——只读访问您的 Google 联系人，以及（对于 Workspace 账号）组织目录。详情请参阅下方的范围用途说明表。

您还必须在重新授权前，于 GCP 项目的 OAuth 授权页面配置中启用 People API 并添加这两个新范围，否则授权页面会拒绝该请求。gws.contacts.directory_search 需要 Google Workspace 账号——个人 Gmail 账号没有组织目录，因此会收到清晰的说明消息，而不是搜索结果。

升级（Google Slides 工具）

Slides 工具（gws.slides.*）新增了一个 OAuth 范围， https://www.googleapis.com/auth/presentations。现有用户必须为每个已连接的账号重新授权，以便生成包含 Slides 范围的新令牌：

/gws:reauth

您还必须在重新授权前，于 GCP 项目的 OAuth 授权页面配置中启用 Slides API 并添加 presentations 范围，否则授权页面会拒绝该请求（请参阅Google Cloud 设置）。重新授权之前，gws.slides.* 调用会返回范围错误，并提示 Agent 运行 gws.accounts.reauth；其他所有工具均可正常使用。

从 v0.2.x 升级

v0.3.0 新增了原生 Google Sheets 和 Google Docs 工具，需要两个新的 OAuth 范围（spreadsheets、documents）。现有用户必须为每个已连接的账号重新授权，以便生成包含这些范围的新令牌：

/gws:reauth

在浏览器中批准授权页面之前，请查看新增范围授予的权限——可对该账号 Google Drive 中的所有电子表格和文档进行完整的读写访问，包括与该账号共享的文件。详情请参阅下方的范围用途说明表。

您还必须在重新授权前，于 GCP 项目的 OAuth 授权页面配置中添加这两个新范围（并启用 Sheets 和 Docs API），否则授权页面会拒绝该请求。

快速入门（Claude Code）

1. 安装插件——在 Claude Code 中运行以下两条命令：

/plugin marketplace add orieg/gws-connector
/plugin install gws@gws-connector

2. 设置 Google Cloud 凭据——交互式向导会引导您完成所有步骤：

/gws:configure

这会创建一个 GCP 项目、启用 API 并连接您的第一个账号。如果您更喜欢手动操作，请参阅Google Cloud 设置。

3. 连接其他账号：

/gws:add-account

每个账号都可以使用来自不同 GCP 项目的不同 OAuth 凭据。

Gemini CLI

gemini extensions install https://github.com/orieg/gws-connector

首次使用时会自动下载二进制文件。然后在 Gemini 中连接账号：

gws.accounts.add(label: "personal", clientId: "your-client-id", clientSecret: "your-secret")

其他客户端

git clone https://github.com/orieg/gws-connector && cd gws-connector && make build

gws.accounts.add(label: "personal", clientId: "your-client-id", clientSecret: "your-secret")

git clone https://github.com/orieg/gws-connector
cd gws-connector
make build
claude --plugin-dir ./

docker run -i --rm ghcr.io/orieg/gws-connector:latest

docker run -i --rm -v gws-state:/state -e GWS_STATE_DIR=/state \
  ghcr.io/orieg/gws-connector:latest

用法

所有 gws.* 工具都接受可选的 account 参数：

# Uses default account
gws.mail.search(q: "is:unread")

# Target by label
gws.cal.list_events(account: "work")

# Target by email
gws.drive.search(account: "[email protected]", q: "quarterly report")

可用工具

技能

Claude Code 和 Gemini CLI 中均可使用的交互式工作流：

使用示例

连接账户后，只需用自然语言向助手提出请求——它会选择工具和账户。示例：

• 跨账户晨间整理 — “汇总我所有账户过去 24 小时内未读的邮件，按账户分组，并标出今天需要回复的邮件。”
• 在线程中起草回复 — “在我的工作账户中找到与 Acme 讨论 Q3 发票的邮件线程，并起草一封确认新日期的回复。不要发送。”
• 将邮件转为日历事件 — “阅读活动团队的最新消息，并根据其中的日期和地点，在我的个人日历上创建日历事件。”
• 跨账户摘要 — “明天我的工作和个人日历上有哪些会议？按时间顺序列在一条时间线上。”
• 查找并总结文档 — “在我的 client-acme Drive 中搜索最新的‘工作说明书’，并列出关键交付成果和日期。”
• 记录到电子表格 — “在我个人 Drive 的‘Expenses’表格中追加一行：今天的日期、‘AWS’、42.50。”
• 保持收件箱整洁 — “将来自 newsletters@ 的所有未读邮件标记为‘Newsletters’，并在我的个人账户中将其标记为已读。”

提示：

• 明确指定账户标签（“在我的工作账户中”）、邮箱地址或域名，以选择目标账户；否则将使用默认账户。
• 写入操作（草稿、事件、表格或文档编辑）会先预览并等待你确认，之后才会发送或更改任何内容。

Google Cloud 设置

一次性设置：

1. 前往 Google Cloud Console 并创建一个新项目（例如，“GWS Connector”）

2. 启用 API — 点击每个链接并点击“启用”：

   • Gmail API
   • Calendar API
   • Drive API
   • Sheets API
   • Docs API
   • People API
   • Tasks API
   • Slides API

3. 配置 OAuth 同意屏幕：

   • 选择“External”（Google Workspace 组织可选择“Internal”）
   • 填写应用名称（例如，“Claude GWS”）和用于支持联系的邮箱
   • 点击“保存”

4. 添加范围 — 前往 数据访问：

   • 点击“添加或移除范围”
   • 添加以下 11 个范围（粘贴到“手动添加范围”框中）：
     • https://www.googleapis.com/auth/gmail.modify
     • https://www.googleapis.com/auth/calendar
     • https://www.googleapis.com/auth/drive
     • https://www.googleapis.com/auth/spreadsheets
     • https://www.googleapis.com/auth/documents
     • https://www.googleapis.com/auth/contacts.readonly
     • https://www.googleapis.com/auth/directory.readonly
     • https://www.googleapis.com/auth/tasks
     • https://www.googleapis.com/auth/presentations
     • https://www.googleapis.com/auth/userinfo.email
     • https://www.googleapis.com/auth/userinfo.profile
   • 点击“更新”，然后点击“保存”

   请求每个范围的原因：

   范围	用途	工具
   gmail.modify	读取、起草和修改邮件及标签	gws.mail.*
   calendar	读取和创建/更新活动	gws.cal.*
   drive	搜索和读取 Drive 中的文件及元数据	gws.drive.*
   spreadsheets	读取和写入 Google Sheets 单元格数据及元数据	gws.sheets.*
   documents	读取和写入 Google Docs 内容	gws.docs.*
   contacts.readonly	只读搜索你自己的 Google Contacts	gws.contacts.search
   directory.readonly	只读搜索 Workspace 组织目录（仅限 Workspace 账号）	gws.contacts.directory_search
   tasks	读取和写入 Google Tasks 列表及任务	gws.tasks.*
   presentations	读取和写入 Google Slides 内容	gws.slides.*
   userinfo.email	识别授权账号（重新授权时匹配邮箱）	账号管理
   userinfo.profile	将显示名称与邮箱一同存储	账号管理

5. 添加测试用户 — 前往 受众群体：

   • 添加你计划连接的每个 Google 邮箱地址
   • ⚠️ 此步骤为必需 — 否则在 OAuth 过程中会出现“访问被拒：尚未完成 Google 验证流程”（错误 403）

6. 创建 OAuth 凭据 — 前往 客户端：

   • 点击“+ 创建客户端” →“OAuth 客户端 ID”
   • 应用类型：桌面应用
   • 点击“创建”
   • 下载 JSON 文件（点击下载图标）— 其中包含你的客户端 ID 和客户端密钥

多个组织

如果你连接来自不同 Google Workspace 组织的账号，每个组织都需要自己的 GCP 项目。请在每个项目中创建 OAuth 凭据，并在连接时提供：

gws.accounts.add(label: "work", clientId: "work-client-id", clientSecret: "work-secret")
gws.accounts.add(label: "personal", clientId: "personal-client-id", clientSecret: "personal-secret")

客户端密钥存储在操作系统密钥链中。客户端 ID 存储在账号注册表中。

架构

gws-connector/
├── cmd/gws-mcp/                 # MCP server entrypoint
├── internal/
│   ├── accounts/                # Account registry & router
│   ├── auth/                    # OAuth flow, token store, client factory
│   ├── server/                  # MCP tool registration & dispatch
│   └── services/                # Gmail, Calendar, Drive API wrappers
│
├── .claude-plugin/              # Claude Code plugin manifest + marketplace
├── .mcp.json                    # Claude Code MCP config
├── gemini-extension.json        # Gemini CLI extension manifest
├── CONTEXT.md                   # Shared behavioral context (both agents)
├── skills/                      # Slash commands (Claude Code + Gemini CLI)
├── hooks/                       # Claude Code session hooks
├── agents/                      # Claude Code workspace agent
│
├── .vscode/mcp.json             # GitHub Copilot MCP config
├── .cursor/mcp.json             # Cursor MCP config
└── codex.json                   # OpenAI Codex CLI config

• 令牌存储：使用 OS 密钥链（macOS Keychain、GNOME Keyring、Windows Credential Manager），并自动回退到文件存储
• 客户端密钥：每个账户存储在 OS 密钥链中（不存储在配置文件中）
• 账户注册表：位于 ~/.claude/channels/gws/accounts.json 的 JSON 文件（包含客户端 ID 和元数据，不含密钥）
• 凭据解析：每个账户的凭据（密钥链）→ 回退到全局环境变量
• 协议：通过 stdio 使用 MCP（Model Context Protocol）——兼容任何 MCP 客户端

开发

make build          # Build binary
make test           # Run tests with race detector
make test-verbose   # Run tests with verbose output
make lint           # Run go vet
make release        # Cross-compile for all platforms
make clean          # Remove build artifacts

许可证

MIT — 请参阅 LICENSE。