GWS连接器
   
多帐户Google Workspace MCP服务器——通过智能路由连接多个Gmail、Google日历和Google Drive帐户。
适用于 克劳德代码, Gemini CLI, GitHub Copilot, 光标, OpenAI 代码专家，以及任何兼容MCP的客户端。
为什么
大多数AI编码助手只支持一个Google帐户。如果你使用多个谷歌帐户（个人+工作、多个客户端、不同的组织），你需要手动在它们之间切换。此MCP服务器允许您一次连接所有请求，并通过标签、电子邮件或域路由请求。
特性
- 多账户 --连接无限的Gmail和Google Workspace帐户
- 智能路由 --按标签定位目标客户(
work)、电子邮件或域 - 每个帐户OAuth --不同的组织可以使用自己的GCP凭据
- 安全存储 --存储在操作系统密钥链中的客户端机密和令牌（Linux上没有GNOME密钥环的文件回退）
- 30工具 --邮件（9）、日历（4）、驱动器（3）、表格（4），文档（4）和帐户管理（6）
- 账户管理 --添加、删除、设置默认值、列出帐户
- 跨平台 --标准MCP服务器适用于任何兼容的客户端
从v0.2.x升级
v0.3.0在两个新的OAuth背后添加了本机Google表格和Google文档工具 范围(spreadsheets, documents). 现有用户必须重新授权 每个连接的帐户 因此，新的令牌是用这些作用域铸造的：
/gws:reauth在批准浏览器同意屏幕之前，请查看新范围 授予对其中每个电子表格和文档的完全读写权限 帐户的Google云端硬盘，包括与帐户共享的文件。请参阅 范围基本原理表 详见下文。
您还必须添加两个新作用域（并启用表格和文档API） 在重新授权之前，在GCP项目的OAuth同意屏幕配置中， 或者同意屏幕将拒绝该请求。
快速入门（克劳德代码）
1.安装插件 --在Claude Code中运行这两个命令：
/plugin marketplace add orieg/gws-connector
/plugin install gws@gws-connector2.设置Google Cloud凭据 --交互式向导将引导您完成所有操作：
/gws:configure这将创建一个GCP项目，启用API，并连接您的第一个帐户（约5分钟）。看 谷歌云设置 如果你喜欢手动步骤。
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")其他客户
GitHub Copilot / Cursor / Codex / Any MCP client
下载a 预构建二进制文件 或从源代码构建：
git clone https://github.com/orieg/gws-connector && cd gws-connector && make build然后配置您的客户端：
| 客户端 | 配置 |
|---|---|
| GitHub Copilot | 自动检测 .vscode/mcp.json，或添加 "command": "/path/to/gws-mcp" 到VS代码MCP设置 |
| 光标 | 自动检测 .cursor/mcp.json，或通过设置添加→ MCP服务器 |
| Codex CLI | 自动检测 codex.json |
| 克劳德代码（仅限MCP） | claude mcp add --transport stdio gws-connector --scope user -- /path/to/gws-mcp --use-dot-names |
| 任何MCP客户端 | gws-mcp [--use-dot-names] 超过stdio |
通过MCP工具调用连接帐户：
gws.accounts.add(label: "personal", clientId: "your-client-id", clientSecret: "your-secret")环境变量（全部可选）： GWS_GOOGLE_CLIENT_ID, GWS_GOOGLE_CLIENT_SECRET, GWS_STATE_DIR
这 --use-dot-names 旗帜用途 gws.mail.search 命名；没有它，工具使用 gws_mail_search.
Local development / testing
git clone https://github.com/orieg/gws-connector
cd gws-connector
make build
claude --plugin-dir ./使用 /reload-plugins 在更改后的会话中。跑 claude --debug --plugin-dir ./ 对插件加载进行故障排除。
用法
全部 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: "alice@company.com", q: "quarterly report")可用工具
| 工具 | 说明 |
|---|---|
gws.accounts.list | 列出所有已连接的帐户 |
gws.accounts.add | 连接新帐户（等待约60秒；返回 pendingId 如果速度较慢） |
gws.accounts.reauth | 重新授权帐户（等待约60秒；返回 pendingId 如果速度较慢） |
gws.accounts.complete | 完成挂起的OAuth流（仅在add/reauth返回时才需要 pendingId) |
gws.accounts.remove | 断开帐户连接 |
gws.accounts.set_default | 更改默认帐户 |
gws.mail.search | 搜索邮件（Gmail查询语法） |
gws.mail.read_message | 阅读特定消息 |
gws.mail.read_thread | 阅读整个帖子 |
gws.mail.create_draft | 创建电子邮件草稿 |
gws.mail.send_draft | 发送现有草稿 |
gws.mail.list_labels | 列出Gmail标签 |
gws.mail.create_label | 创建新标签 |
gws.mail.modify_message | 添加/删除邮件上的标签 |
gws.mail.get_profile | 获取帐户配置文件信息 |
gws.cal.list_events | 列出日历事件 |
gws.cal.get_event | 获取活动详细信息 |
gws.cal.create_event | 创建日历事件 |
gws.cal.list_calendars | 列出可用日历 |
gws.drive.search | 在驱动器中搜索文件 |
gws.drive.read_file | 读取文件内容/元数据 |
gws.drive.list_folder | 列出文件夹内容 |
gws.sheets.read_range | 从电子表格中读取单个A1范围 |
gws.sheets.write_range | 将单元格值写入范围 |
gws.sheets.create | 创建新的电子表格 |
gws.sheets.list_tabs | 在电子表格中列出选项卡（工作表） |
gws.docs.read | 以纯文本形式阅读文档 |
gws.docs.insert_text | 在某个位置插入文字 |
gws.docs.replace_text | 替换所有出现的文字子字符串 |
gws.docs.create | 创建新文档 |
技能
Claude Code和Gemini CLI中都提供交互式工作流：
| 技能 | 描述 | 克劳德代码 | Gemini CLI |
|---|---|---|---|
| configure | 交互式安装向导 | /gws:configure | “运行GWS配置技能” |
| 添加帐户 | 连接新帐户 | /gws:add-account | “添加新的GWS帐户” |
| 删除帐户 | 断开帐户连接 | /gws:remove-account | “删除GWS帐户” |
| 列出帐户 | 显示已连接的帐户 | /gws:list-accounts | “列出我的GWS帐户” |
| 设置默认值 | 更改默认帐户 | /gws:set-default | “设置我的默认GWS帐户” |
| reauth | 刷新令牌/作用域 | /gws:reauth | “重新认证我的GWS帐户” |
谷歌云设置
一次性设置（约5分钟）：
- 首选 谷歌云控制台 并创建一个新项目（例如“GWS连接器”）
- 启用API --点击每个链接并点击“启用”：
- Gmail API - 日历API - 驱动API - 表API - API文档
- 配置 OAuth 同意屏幕:
- 选择“外部”（或谷歌工作区组织的“内部”） - 填写应用程序名称（例如“Claude GWS”）和您的支持联系人电子邮件 - 点击“保存”
- 添加作用域 首选 数据访问:
- 点击“添加或删除范围” - 添加这7个范围（粘贴到“手动添加范围”框中）： - 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/userinfo.email - https://www.googleapis.com/auth/userinfo.profile - 点击“更新”，然后点击“保存”
为什么要求每个范围：
| 范围 | 目的 | 工具 |
|---|---|---|
gmail.modify | 阅读、起草、修改消息和标签 | gws.mail.* |
calendar | 读取和创建/更新事件 | gws.cal.* |
drive | 在驱动器中搜索和读取文件和元数据 | gws.drive.* |
spreadsheets | 读取和写入Google表格单元格数据和元数据 | gws.sheets.* |
documents | 读写谷歌文档内容 | gws.docs.* |
userinfo.email | 识别授权帐户（reauth上的电子邮件匹配） | 帐户管理 |
userinfo.profile | 在电子邮件旁边存储显示名称 | 帐户管理 |
- 添加测试用户 首选 观众:
- 添加您计划连接的每个Google电子邮件地址 - ⚠️ 这是必需的 --如果没有这个，您将在OAuth期间收到“访问被阻止：尚未完成谷歌验证过程”（错误403）
- 创建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- 令牌存储：具有自动文件回退功能的操作系统密钥链（macOS密钥链、GNOME密钥环、Windows凭据管理器）
- 客户机密：每个帐户的操作系统密钥链（不存储在配置文件中）
- 帐户注册表：JSON文件位于
~/.claude/channels/gws/accounts.json（包含客户端ID和元数据，没有秘密） - 凭证解析：每个帐户凭据（钥匙链）→ 全局环境变量回退
- 协议：基于stdio的MCP（模型上下文协议）——与任何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许可证
麻省理工学院——见 许可证.